Alexandria

Alexandria

Install in Goose

一个用于查询、阅读和导入来自 152 个公共数字图书馆文本的模型上下文协议（MCP）服务。可与任何兼容 MCP 的客户端配合使用（Claude Desktop、Cursor、VS Code Copilot 等）。

工具

工具	描述
library_list_sources	列出全部 152 个来源及其描述和全文支持情况
library_ask(query, max_sources?, results_per_source?)	自然语言搜索——将查询路由到最合适的来源，并行搜索，返回统一且去重的结果
library_search(query, source, limit?)	按标题、作者或关键词搜索指定来源
library_read(id, source)	获取条目的全文或元数据（上限为 200k 个字符）
library_index(id, source)	试运行：对文本分块并评估质量，不写入任何内容
library_ingest(id, source)	分块 → 嵌入 → 存储到你的向量数据库中。支持幂等操作。
library_recommend(id, limit?)	通过 Semantic Scholar 的推荐引擎获取相似论文（最多 500 篇）
library_answer(query, max_sources?, results_per_source?, read_top?)	提出问题并获取综合答案，附带行内 [n] 引文；通过倒数排名融合整合各来源；warnings[] 标记缺少引文或所有结果均被舍弃的答案
library_research(query, depth?, breadth?, max_minutes?)	递归式多轮研究：生成查询、逐一回答、提取要点，并根据找到的所有来源撰写最终引文报告
library_health_check(source?, cluster?)	报告各来源的健康状况（ok、degraded、down、key_missing、unknown），并将此进程的实时错误率和延迟与上一次在进程外运行的探测结果合并
library_citations(id, source, direction, limit?, format?)	通过 OpenAlex 的引文图谱列出某条目引用的作品（direction: "references"）或引用该条目的作品（direction: "citations"）；使用 OpenCitations 作为后备方案；format: "bibtex" | "ris" | "apa" 还会返回格式化的书目字符串

library_ask 是主要入口。library_search 用于针对已知来源进行定向查询。library_index / library_ingest 用于根据检索到的文本构建向量知识库。library_answer 和 library_research 用于综合生成带引文的答案或报告，而不是返回原始结果。调用来源之前，可使用 library_health_check 判断是否值得查询。library_citations 会遍历某条目周围的引文图谱，并可将其导出为书目。

library_ask、library_search、library_answer、library_research、library_health_check 和 library_citations 接受 response_format: "concise" | "detailed" 参数（默认值为 concise）；concise 会将结果和引文精简为关键信息字段（标题、来源、id、年份、hasFullText、url；答案／报告 + 引文；名称、集群、状态），detailed 会返回完整内容，包括路由原因、相关性评分、各阶段诊断信息以及各来源的错误率／延迟／配额使用情况。在 detailed 模式下，library_search 还会为每个全文结果附加一个 resource_link 内容项，指向该条目的 library://doc/{source}/{id} 资源（见下文）：支持资源的客户端可以直接读取全文，无需再次调用 library_read。

提示词

三个现成的研究工作流，由 MCP 客户端作为斜杠命令提供（Claude Code 的 /alexandria:<name>、VS Code 的 /alexandria.prompt）。每个工作流都会返回一条消息，按顺序列出要调用的工具。它本身不会调用任何工具。

提示词	描述
literature_review(topic, depth?)	跨来源调研某个主题，并撰写带引文的报告
fact_check_claim(claim)	根据知识库核查一项主张，并报告其是否有依据
verify_bibliography(references)	检查一组参考文献（每行一条）能否对应到真实且可检索的条目

资源

library://doc/{source}/{id} 会读取与 library_read(id, source) 返回内容相同的文本（包括下方的开放访问回退内容），由 library_search 或 library_ask 返回的 source/id 组合寻址。支持 MCP 资源的客户端（Claude Code 的 @srv:uri、VS Code 的 Add Context）可以直接拉取条目的全文。

来源（152）

共有 152 个来源，分布在 19 个集群中（其中 36 个因本次部署缺少密钥或配置而隐藏）。包含身份验证环境变量和最近验证日期在内的每个来源完整详情，见 docs/sources.md。

集群	来源	隐藏
academic	22	3
ai_research	3	0
archives	4	2
culture	8	3
developer	17	5
economics	11	3
geopolitical	3	3
government	7	3
law	4	1
literature	16	2
markets	2	1
news_global	5	2
news_regional	15	0
real_estate	2	2
science	8	2
security	14	0
standards	3	0
video	1	1
web	7	3
总计	152	36

凭据

大多数工具直接查询外部图书馆 API，无需任何凭据。两个可选依赖仅供特定工具使用：

OpenAI，可选（platform.openai.com）

仅以下两个工具需要：

• library_ask：使用 gpt-4o-mini 将自然语言查询路由到合适的来源，并生成优化后的各来源搜索词。没有此密钥时，可使用 library_search 直接查询来源。
• library_ingest：使用 text-embedding-3-small 在将分块文本写入向量存储之前生成嵌入。

library_list_sources、library_search、library_read、library_index 和 library_recommend 均无需 OpenAI 密钥。

将角色指向网关，而不是直接连接 OpenAI

每次 LLM/嵌入调用（library_ask 中的路由、library_ingest 中的嵌入）都会通过一个小型的按角色划分的提供方表（src/utils/providers.ts，THE-318），而不是直接调用 OpenAI 的 SDK。共有五种角色：router、synth、research、embeddings、rerank。每种角色按以下顺序从环境变量中解析：

1. ALEXANDRIA_<ROLE>_BASE_URL、ALEXANDRIA_<ROLE>_API_KEY、ALEXANDRIA_<ROLE>_MODEL（按角色覆盖；<ROLE> 为大写的角色名称，例如 ALEXANDRIA_ROUTER_BASE_URL）
2. ALEXANDRIA_BASE_URL、ALEXANDRIA_API_KEY（所有角色共用的默认值）
3. OPENAI_API_KEY，baseURL 默认为 https://api.openai.com/v1

如果只设置了 OPENAI_API_KEY，所有角色都会通过第 3 步解析，这与目前的行为完全一致（router/synth 使用 gpt-4o-mini，连接到 api.openai.com；embeddings 使用 text-embedding-3-small）。

要将所有角色都路由到 LiteLLM 网关：

ALEXANDRIA_BASE_URL=http://100.78.123.100:4001/v1
ALEXANDRIA_API_KEY=sk-litellm-...

要通过 Cloudflare AI Gateway（其 OpenAI 兼容端点）路由：

ALEXANDRIA_BASE_URL=https://gateway.ai.cloudflare.com/v1/<account_id>/<gateway_id>/openai
ALEXANDRIA_API_KEY=<your OpenAI key, forwarded through the gateway>

也可以只将一个角色指向网关，其余角色仍直接连接 OpenAI，例如，只为路由设置 ALEXANDRIA_ROUTER_BASE_URL + ALEXANDRIA_ROUTER_API_KEY。

有关更完整的 Cloudflare 集成指南，请参阅 docs/cloudflare.md：AI Gateway 较新的统一端点、用于 embeddings/rerank 角色的 Workers AI、用于私有 /mcp 的 Tunnel + Access、用于公共 /mcp 的 WAF 速率限制、作为可选缓存存储的 R2、下文所述的 Browser Run 抓取层，以及 Alexandria 为何采用混合架构（Node 核心、Cloudflare 服务），而不是完整移植到 Workers。

当设置了 ALEXANDRIA_<ROLE>_BASE_URL/ALEXANDRIA_BASE_URL 且 同时存在 OPENAI_API_KEY 时，OPENAI_API_KEY 会被配置为一次性回退方案：如果网关发生网络错误或返回 5xx，则会在请求失败前回退到 OpenAI 直接调用一次。chatJSON（用于路由）始终会根据 zod schema 验证模型的响应，并在同一后端重试一次，同时将验证错误附加到提示词中；当网关代理的是较小模型或本地模型，而该模型无法稳定地在首次尝试时遵守 JSON 约定时，这会有所帮助。只有连接 api.openai.com 时，或通过 ALEXANDRIA_<ROLE>_JSON_MODE=1 确认网关/模型支持时，才会请求 response_format: json_object；否则会在提示词中要求返回 JSON。

Supabase — 可选（supabase.com）

只有一个工具需要它：

• library_ingest — 将分块后的嵌入文本写入 pgvector 表，以便进行语义搜索。没有它，检索到的文本只会保留在上下文中，不会持久化到任何位置。

其他所有功能——搜索、阅读、浏览、获取推荐——都会实时查询外部来源，无需数据库。

各来源专属密钥

某些来源需要自己的 API 密钥。注册免费。此处未列出密钥的来源无需任何凭据即可使用。

Env Var	Source(s)	Get It
CORE_API_KEY	core	core.ac.uk/services/api
COURTLISTENER_API_KEY	courtlistener	courtlistener.com/profile/tokens
GOVINFO_API_KEY	govinfo；congress 和 regulations 也接受此密钥，作为 DATA_GOV_API_KEY 的备用项	api.data.gov/signup。不适用于 smithsonian，后者需要在同一注册页面申请自己的 SMITHSONIAN_API_KEY
GOOGLE_BOOKS_API_KEY	googlebooks	Google Cloud Console → APIs & Services → Books API
BHL_API_KEY	bhl	biodiversitylibrary.org/getapikey
DIGITALNZ_API_KEY	digitalnz	digitalnz.org/developers
DPLA_API_KEY	dpla	pro.dp.la/developers/api-codex
EUROPEANA_API_KEY	europeana	apis.europeana.eu — 测试密钥可立即获取，个人密钥约需 1 周
GITHUB_TOKEN	githubsearch 和 githubmcp 必需；ghsa 和 openiti 可选	github.com/settings/tokens，需要公开仓库读取权限。未提供此密钥时，githubsearch 和 githubmcp 会被隐藏；ghsa 会改为每 60s 请求一次，openiti 会改用未经身份验证的搜索路径
NASA_ADS_API_KEY	nasaads	ui.adsabs.harvard.edu/user/settings/token
SPRINGER_OA_API_KEY + SPRINGER_META_API_KEY	springer	dev.springernature.com — 同一次注册可获取两个密钥
ZENODO_API_KEY	zenodo	zenodo.org/account/settings/applications/tokens/new — 可选，能提高速率限制
SMITHSONIAN_API_KEY	smithsonian	api.data.gov/signup。需要单独申请，不同于 GOVINFO_API_KEY
SEMANTIC_SCHOLAR_API_KEY	semanticscholar	semanticscholar.org/product/api — 可选，能提高速率限制
TROVE_API_KEY	trove	trove.nla.gov.au/about/create-something/using-api — 审批约需 1 周
YOUTUBE_API_KEY	youtube	console.cloud.google.com — 启用 YouTube Data API v3；仅搜索需要，获取字幕无需密钥

隐私政策

Alexandria 本身不收集遥测数据：它运行在由你控制的基础设施上，关于你的查询、结果或凭据的任何信息都不会发送给 Alexandria 项目。

• 查询会发送到 Agent 针对特定请求选定的上游公共图书馆来源，并使用各来源自己的公共 API，遵循各自的条款。
• 如果配置了 OpenAI（或兼容 OpenAI 的网关）密钥，library_ask、library_answer、library_research 和 library_ingest 也会将你的查询文本和检索到的摘录发送给运营方配置的大模型和嵌入服务提供商。有关 Cloudflare AI Gateway 路由路径，请参阅 docs/cloudflare.md；有关如何防护对图书馆来源的出站请求，请参阅 docs/fetch-tier-runtime.md。
• 项目本身不会存储任何内容。运营方自己的 data/ 目录会在运行服务的机器上保存本地缓存（状态数据库、每个进程的读取缓存），仅此而已。

全文：PRIVACY.md。

设置

git clone https://github.com/The-40-Thieves/alexandria-mcp
cd alexandria-mcp
npm install
npm run build

将 .env.example 复制为 .env。无需凭据即可运行（仅搜索和读取）的最低配置：

TRANSPORT=stdio

启用 library_ask：

TRANSPORT=stdio
OPENAI_API_KEY=sk-...

启用 library_ingest：

TRANSPORT=stdio
OPENAI_API_KEY=sk-...
SUPABASE_URL=https://your-project.supabase.co
SUPABASE_SERVICE_ROLE_KEY=eyJ...

Supabase 架构

仅在使用 library_ingest 时需要：

create table if not exists knowledge_chunks (
  id bigserial primary key,
  content text not null,
  embedding vector(1536),
  mcp_name text,
  metadata jsonb,
  created_at timestamptz default now()
);

create table if not exists source_docs (
  id bigserial primary key,
  source_url text not null,
  mcp_name text not null,
  title text,
  source text,
  chunk_count int,
  indexed_at timestamptz,
  unique (source_url, mcp_name)
);

create index if not exists knowledge_chunks_embedding_hnsw_idx
  on knowledge_chunks using hnsw (embedding vector_cosine_ops);

如果你在 Task 12 之前设置了此架构，则使用的是 ivfflat 索引 （knowledge_chunks_embedding_idx）——docs/sql/match_chunks.sql 会删除该索引，并 创建上面所示的 hnsw 索引，因为 HNSW 会增量构建，并且随着表增长，无需 调整 lists 常量。如果作为缓存的语料库查询似乎遗漏了普通 <=> 扫描本可 找到的结果，可以提高查询时的 hnsw.ef_search 会话设置（默认值为 40）， 代价是查询变慢——请参阅 docs/sql/match_chunks.sql 中的注释建议。

将语料库用作缓存

library_answer 也可以直接读取 knowledge_chunks 中已摄取并完成嵌入的 文本，作为与实时的逐来源搜索并列的另一个排序列表；如果缓存中已有完整文本， 就会跳过网络请求。它只会提供注册表新鲜度为 static 或 daily 的来源中的 文本块（绝不会提供 realtime 来源），且余弦相似度必须高于 ALEXANDRIA_CORPUS_MIN_SIM（默认值为 0.92）。

除上面的表之外，还需要额外设置一部分架构：在 Supabase SQL 编辑器中运行 docs/sql/match_chunks.sql。该文件定义了 match_knowledge_chunks()，即 SupabaseVectorStoreProvider.query() 通过 .rpc() 调用的近邻搜索函数，以及上面的 hnsw 索引。此文件根据当前的 pgvector/supabase-js 文档编写，但尚未在实时数据库上运行过—— 在依赖它之前，请在你自己的项目中验证。

Claude Code（npx）

claude mcp add --env OPENAI_API_KEY=sk-... alexandria -- npx -y @the-40-thieves/alexandria-mcp

搜索和读取功能完全无需环境变量；只有启用 library_ask、 library_answer、library_research 和 library_ingest 才需要使用上面的 --env 标志。可选键的完整列表请参阅凭据。

Claude Desktop（stdio）

最低配置（仅搜索和读取），通过 npx 使用已发布的包：

{
  "mcpServers": {
    "library": {
      "command": "npx",
      "args": ["-y", "@the-40-thieves/alexandria-mcp"],
      "env": {
        "TRANSPORT": "stdio"
      }
    }
  }
}

启用 library_ask 和 library_ingest：

{
  "mcpServers": {
    "library": {
      "command": "npx",
      "args": ["-y", "@the-40-thieves/alexandria-mcp"],
      "env": {
        "TRANSPORT": "stdio",
        "OPENAI_API_KEY": "sk-...",
        "SUPABASE_URL": "https://your-project.supabase.co",
        "SUPABASE_SERVICE_ROLE_KEY": "eyJ..."
      }
    }
  }
}

如果使用本地检出版本而非已发布的包，请将 command/ args 替换为 "command": "node", "args": ["/path/to/alexandria-mcp/dist/index.js"]。

Railway（HTTP）

HTTP 模式默认关闭。设置 TRANSPORT=http 后，将在 /mcp 上提供 Streamable HTTP，而不是通过 stdio 通信；设置 PORT 可选择监听端口 （默认值为 3000；Railway 会为你设置 PORT）。每个请求都会创建独立的 MCP 服务和传输，因此端点是无状态的，可安全地置于负载均衡器后运行。

环境变量	值	默认值
TRANSPORT	stdio 或 http	stdio
PORT	任意端口号，仅限 HTTP 模式	3000

仅 /mcp 受到保护：验证 Host/Origin 以防止 DNS 重绑定 （ALEXANDRIA_ALLOWED_ORIGINS，以逗号分隔的主机名列表——无论如何都会允许 回环地址），并对每个客户端 IP 限速 （ALEXANDRIA_HTTP_RATE_LIMIT，默认每分钟 60 次；超过限制后返回带有 JSON-RPC 错误正文的 429）。详情请参阅 docs/fetch-tier-runtime.md，实现请参阅 src/httpGuards.ts。

任何可通过非回环主机名访问的部署，都必须设置 ALEXANDRIA_ALLOWED_ORIGINS。 如果未设置，Host 标头验证将 关闭，且服务启动时会记录一条警告说明此情况：部署的 Host 标头就是其自身主机名，而不存在的允许列表不可能包含该主机名， 因此在没有允许列表时强制检查会导致所有请求都返回 403。 设置该变量即可启用 DNS 重绑定防护。无论是否设置该变量，Origin 检查都始终启用， 因此，携带允许列表之外 Origin 的浏览器请求始终会被拒绝。

POST /mcp 要求 content-type: application/json（否则返回 415），且请求正文不得超过 100 KiB（否则返回 413 并关闭连接）。 在反向代理或 PaaS 边缘节点（Cloudflare Tunnel、Railway 自带的边缘节点，……）后面，速率限制器的客户端键默认使用 req.socket.remoteAddress，但对每个调用者来说，这都是代理的地址，而不是调用者的地址。设置 ALEXANDRIA_TRUSTED_PROXY=1，即可改用 CF-Connecting-IP（如果没有，则使用 X-Forwarded-For 最右侧的条目，也就是最后一跳追加的条目；最左侧的条目是原始调用者发送的内容）。只有当 /mcp 只能通过你信任且会如实设置这些标头的代理访问时，才设置此项——参见 docs/cloudflare.md 中的 Tunnel 和 Access 部分。

在同一个 /mcp 端点上同时提供 MCP 协议的两个时期版本： createMcpHandler(factory, { legacy: 'stateless' })（@modelcontextprotocol/server，由 @modelcontextprotocol/node 中的 toNodeHandler() 适配为 node:http）会在现代路径上响应 2026-07-28 的 server/discover 探测或逐请求信封，并回退到 2025 年时期的 initialize 握手所用的相同无状态惯用模式，即 2026 年之前 SDK 所采用的模式。两种模式都由一个 createServer() 工厂提供支持。stdio 使用来自 @modelcontextprotocol/server/stdio 的连接固定式 serveStdio(factory)，它会根据连接的初始交换选择协议时期。注意：2025 年时期的回退路径通过 text/event-stream（SSE）响应，而不是直接返回 JSON 正文，因为 SDK 没有为该路径提供与 v1 的 enableJsonResponse 等效的选项。任何基于 Streamable HTTP 传输的 MCP 客户端（包括 SDK 自带的 StreamableHTTPClientTransport）都已能透明地解析这两种格式。

在 Railway 控制面板中设置这些变量（以及任何来源键），然后部署：

railway up

在本地执行相同操作：

TRANSPORT=http PORT=3000 npm start

在 Claude Desktop 中注册：

{
  "mcpServers": {
    "library": {
      "url": "https://your-service.up.railway.app/mcp"
    }
  }
}

健康检查：GET /health 返回 { status: "ok", version: "11.0.0", sources: { total: 152, visible: 116, hidden: 36, calls: 0, errors: 0 }, byKind: { rest: 118, hub: 0, rss: 22, mcp: 6, scrape: 6 }, quota: { day: "2026-09-02", reserved: 0, sources: 0, backend: "state" }, cache: { entries: 0 }, tools: 11 }。

指标：GET /metrics 以 JSON 格式返回各来源计数器（calls、errors、timeouts、cacheHits、quotaRejections、latencyMsTotal）和各工具计数器（invocations、llmCalls），例如 { "sources": { "arxiv": { "calls": 12, "errors": 0, "timeouts": 0, "cacheHits": 3, "quotaRejections": 0, "latencyMsTotal": 4210 } }, "tools": { "library_ask": { "invocations": 5, "llmCalls": 5 } } }。只会显示进程启动后实际调用过的来源和工具。

在其他客户端中安装

以下配置均通过 npx 运行已发布的软件包；无需环境变量即可进行搜索和读取，添加 --env/环境变量块即可像上文 Claude Code 和 Claude Desktop 部分一样启用 library_ask、library_answer、library_research 和 library_ingest。

GitHub Copilot - .vscode/mcp.json：

{
  "servers": {
    "alexandria": {
      "command": "npx",
      "args": ["-y", "@the-40-thieves/alexandria-mcp"]
    }
  }
}

Windsurf - mcp_config.json：

{
  "mcpServers": {
    "alexandria": {
      "command": "npx",
      "args": ["-y", "@the-40-thieves/alexandria-mcp"]
    }
  }
}

Codex CLI：

codex mcp add alexandria -- npx -y @the-40-thieves/alexandria-mcp

OpenCode - opencode.json：

{
  "mcp": {
    "alexandria": {
      "type": "local",
      "command": ["npx", "-y", "@the-40-thieves/alexandria-mcp"]
    }
  }
}

Amazon Q - ~/.aws/amazonq/mcp.json（全局）或 q mcp add：

{
  "mcpServers": {
    "alexandria": {
      "command": "npx",
      "args": ["-y", "@the-40-thieves/alexandria-mcp"]
    }
  }
}

Kiro - .kiro/settings/mcp.json：

{
  "mcpServers": {
    "alexandria": {
      "command": "npx",
      "args": ["-y", "@the-40-thieves/alexandria-mcp"]
    }
  }
}

Gemini CLI：

gemini extensions install https://github.com/The-40-Thieves/alexandria-mcp

Continue - 添加到 Continue 配置中的 mcpServers 数组：

{
  "name": "alexandria",
  "command": "npx",
  "args": ["-y", "@the-40-thieves/alexandria-mcp"]
}

添加自定义提供程序

该管线与提供程序无关。若要添加新的嵌入模型或向量存储：

1. 实现 src/types.ts 中的 EmbeddingProvider 或 VectorStoreProvider
2. 将实现添加到 src/pipeline/providers/
3. 在 src/pipeline/providers/index.ts 中注册
4. 在环境变量中设置 EMBEDDING_PROVIDER 或 VECTOR_STORE_PROVIDER

// Example: Ollama embedding provider
import type { EmbeddingProvider } from '../../types.js';

export class OllamaEmbeddingProvider implements EmbeddingProvider {
  readonly dimensions = 768;

  async embed(texts: string[]): Promise<number[][]> {
    // your implementation
  }
}