Conceptio Search

conceptio-search

直接在终端或 AI Agent 中搜索 100 万余份开放获取文档——论文、标准、教科书和判例法。

conceptio-search 是一个 CLI 和 Model Context Protocol (MCP) 服务，用于访问 Conceptio Open Knowledge Archive——该档案收录了来自 500 多个持续更新来源的 100 万余份开放获取文档，每日编入索引。所有来源均为开放获取或公有领域。CLI 使用 API 密钥进行身份验证：登录一次，保存密钥，即可随处搜索。

• 面向用户 — 搜索、以 11 种格式导出引文（BibTeX、APA、MLA、Chicago、IEEE、Harvard、RIS、Bluebook、OSCOLA、ISO 690、ANSI Z39），并通过一条命令将 PDF 下载到磁盘。
• 面向 AI Agent — 一个提供九种工具的 stdio MCP 服务，让 Claude、Cursor、Windsurf、OpenCode 或任何 MCP 客户端都能搜索、加入批量搜索队列、解析标识符（RFC、DOI、arXiv、PMID、PMCID、NIST/FIPS、W3C、美国判例引文）、浏览引用关系图、将 PDF 保存到工作区，以及将文档交给 Zotero 或 Obsidian。
• 100% 独立运行 — 仅与公共 HTTPS API 通信。没有内部基础设施；密钥保存在 ~/.conceptio/config.json 中。

---

安装

pip install conceptio-search

需要 Python 3.8+。（经过验证，而非仅仅声称：测试套件会根据声明的最低版本语法解析每个源文件，因此这一承诺不会悄无声息地失效。）

控制台脚本为 conceptio；对于从未激活过的虚拟环境，python -m conceptio_cli 是相同的入口点。

---

身份验证（仅需一次）

CLI 需要 API 密钥才能搜索：

conceptio auth ckey_live_...

登录 conceptio.app，并在个人资料中创建密钥（Free、Dev、Pro 或 Enterprise），即可获取密钥。密钥保存在 ~/.conceptio/config.json 中，并在每次请求时作为 X-Api-Key 发送。conceptio quota 可随时报告你的套餐等级。以下所有命令均假定已完成此步骤——没有密钥时，CLI 会拒绝运行并明确告知原因。

---

快速入门

# Search — supports source:/lang:/category: directives
conceptio search "attention is all you need" --limit 5
conceptio search "source:nist zero trust" --license commercial-ok
conceptio search "source:eurlex AI act" --json
conceptio search "meditations marcus aurelius" --markdown   # for Obsidian/Notion
conceptio search "diffusion models" --offset 20            # paginate past the first page
# Multi-query programmatic search — two modes:
conceptio search --batch queries.json --json                # queue 1–50 searches, print the job handle
conceptio search --batch queries.json --wait --json         # queue, then block until done and print results
conceptio search --batch queries.json --wait --timeout 60   # …but never block longer than a minute
conceptio search --batch queries.json --sync --json         # run 1–10 immediately, no queue (one request)
conceptio search-job <job-id> --json                        # poll once; repeat on your own cadence
conceptio search-job <job-id> --wait --json                 # poll until done, then print results

# Resolve a known identifier straight to its document(s)
conceptio resolve "RFC 2119"
conceptio resolve "doi:10.1109/access.2020.2986772"
conceptio resolve "2604.08499"                              # arXiv
conceptio resolve "PMID 41961061"                           # PubMed
conceptio resolve "PMC10601397"                             # PubMed Central
conceptio resolve "NIST FIPS 199"
conceptio resolve "347 U.S. 483"                            # US case citation (Supreme Court)
conceptio resolve "20-5364"                                 # federal docket
conceptio resolve "RFC 2119" --json

# Download the original PDF
conceptio download 297465 -o paper.pdf          # by document ID
conceptio download "https://arxiv.org/pdf/2604.21816v1.pdf"   # by URL

# Citations — 11 formats: bibtex, apa, mla, chicago, ieee, harvard,
# ris, bluebook, oscola, iso690, ansiz39
conceptio cite 7288 --format bibtex
conceptio cite 7288 --format apa
conceptio cite 7288 --format iso690

# Document metadata
conceptio info 2844
conceptio proof 2844                # machine-readable evidence bundle
conceptio proof 2844 -q "quantum"   # passage-level proof for a phrase

# License key (Pro) or API key + quota
conceptio auth CONCEPTIO-XXXX-XXXX-XXXX   # Pro license (one-time, account-bound)
conceptio auth ckey_live_...              # API key (agent/machine credential)
conceptio quota
conceptio quota --json                    # {tier, auth, credits…} for a status surface

# The flag may come before the subcommand, the way machine callers write it
conceptio --json search "zero trust"

# Version
conceptio --version

# AI agent server
conceptio mcp

示例

$ conceptio search "source:nist zero trust" --limit 3

Conceptio - 3 results for "source:nist zero trust"
  #  Year  Title                                       Author                  Source           PDF
  1  n.d.  NIST SP 1800-35: Implementing a Zero Trust  Scott Rose (NIST); …    NIST             [x]
  2  n.d.  NIST SP 800-207: Zero Trust Architecture     Scott Rose (NIST); …    NIST             [x]
  3  n.d.  NIST SP 800-207A: A Zero Trust Architecture Ramaswamy Chandramo…   NIST             [x]

  Tip: conceptio download 2844 saves the PDF, conceptio cite 2844 exports a citation.

标题列中会以金色突出显示查询词。PDF 列在有直接 PDF 链接时显示 [x]；显示 [ ] 的行仍可通过 conceptio info <id> 获取来源 URL。

搜索指令

CLI 支持与 Conceptio 网页应用相同的指令——这些指令会从查询中移除，并作为实际筛选条件应用：

指令	示例	效果
source: / src:	source:nist	限定一个或多个来源（source:nist source:owasp）
lang: / language:	lang:it	限定语言（ISO 代码）
category: / cat:	cat:"Law & Regulation"	限定类别标签页
--license commercial-ok	--license commercial-ok	仅保留目录元数据明确允许商业使用的来源；这是一个保守筛选条件，并非再分发授权。

指令可自由组合：conceptio search "cat:\"Computer Science & Tech\" source:nist lattice cryptography"。

解析

conceptio resolve 可识别多种标识符格式，并返回带类型的响应（kind: rfc | doi | arxiv | pmid | pmcid | nist | w3c | case，纯文本则回退为 null）。无法识别的标识符会退化为常规搜索，因此命令绝不会悄无声息地失败。

kind 描述的是标识符，而非档案：格式正确但该档案未收录的 DOI，会返回 kind: "doi"、total: 0 和空的 results 列表。这是正确的空结果，而不是失败。以上每个示例目前至少都能解析出一份文档——用于针对线上 API 测试随 CLI 一同发布版本的测试套件会准确断言这一点，因此只有跳过该检查时，示例才可能失效。

---

Model Context Protocol (MCP)

conceptio mcp 命令会启动一个 stdio JSON-RPC MCP 服务。它无需依赖 （不需要 MCP SDK），并且适用于任何 MCP 客户端。

该服务兼容两个时期：既支持当前的 2026-07-28 修订版—— 每个请求的 _meta、server/discover、resultType、缓存提示——也继续 支持较早的 initialize 握手（2024-11-05 … 2025-11-25），以兼容在此之前发布的客户端。 同时支持两个时期的客户端会先通过 server/discover 探测并找到我们；使用握手的客户端则会获得与以往完全相同的服务。

调用工具需要密钥。 服务启动时没有密钥，因此宿主可以发现它并读取工具列表——之后，每次 tools/call 请求都会收到一条带内错误，其中包含设置步骤。无论采用哪种方式，都需要向服务提供密钥：运行一次 conceptio auth <key>，或通过宿主自身的环境变量提供密钥，官方目录列表就是通过这种方式声明密钥的：

{ "mcpServers": { "conceptio": { "command": "conceptio", "args": ["mcp"],
                                "env": { "CONCEPTIO_API_KEY": "ckey_live_…" } } } }

工具

工具	描述
conceptio_search	搜索档案（query、可选的 limit 1–20、可选的 category）。返回结构化结果，包括标题、作者、年份、来源、摘要，以及可用时的 direct_pdf_url。
conceptio_search_batch	在一次调用中运行多次搜索——将 1–50 个搜索作为后台任务排队并返回不透明句柄（省略 sync 或设为 false），或设置 sync: true 以立即运行 1–10 个搜索，并在一个响应中返回所有结果。
conceptio_resolve	将已知标识符解析为对应文档——RFC（RFC 2119）、DOI（doi:10.1109/access.2020.2986772）、arXiv（2604.08499）、PubMed ID（PMID 41961061）、PubMed Central ID（PMC10601397）、NIST/FIPS 编号（NIST FIPS 199）、W3C 规范简称（w3c_digital-credentials）或美国法律引注／案号（347 U.S. 483、20-5364）。无法识别的标识符会回退到文本搜索。
conceptio_download_pdf	将 Conceptio 文档 ID 对应的原始开放获取 PDF，或直接 PDF URL，下载到本地路径。
conceptio_get_citation	获取文档 ID 对应的引文，支持 11 种格式（BibTeX、APA、MLA、Chicago、IEEE、Harvard、RIS、Bluebook、OSCOLA、ISO 690、ANSI Z39）。
conceptio_get_document	获取文档 ID 的完整元数据（标题、作者、来源、类别、许可证、年份、语言、URL、直接 PDF URL、描述）。
conceptio_graph_walk	从种子 source_id 遍历引用图——它引用了什么（direction: 'out'）、什么引用了它（'in'），或两者兼有（'both'）——可遍历一跳或两跳，也可按 cites／updates 关系类型筛选。返回带有节点到种子距离的节点，以及标明关系类型的规范化边。仅处理元数据，不消耗额度。
conceptio_connectors_send	将一份文档保存到 Zotero，或打开仅包含元数据的 Obsidian 交接页面。适用服务端所有权、连接器试用和失败语义。
conceptio_connectors_send_all	批量将最多 500 个文档 ID 保存到 Zotero。需要 Pro、机构版或授权访问权限——不提供免费试用。

Claude Desktop

添加到 claude_desktop_config.json：

• macOS： ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows： %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "conceptio": {
      "command": "conceptio",
      "args": ["mcp"]
    }
  }
}

Cursor

Settings → Cursor Settings → MCP → Add new MCP server：

{
  "mcpServers": {
    "conceptio": {
      "command": "conceptio",
      "args": ["mcp"]
    }
  }
}

OpenCode / Windsurf / Antigravity

相同的 JSON 结构适用于任何支持 MCP 的客户端——将其指向 conceptio mcp 即可自动启用上述九种工具。MCP 宿主可以通过环境变量（CONCEPTIO_API_KEY，或已登录会话使用的 CONCEPTIO_BEARER_TOKEN）提供凭据，而不必写入 ~/.conceptio/config.json。

添加后，重启客户端即可提出此类请求：

“查找 NIST 后量子加密标准，并将 PDF 下载到我的工作区。”

手动冒烟测试

echo '{"jsonrpc":"2.0","id":1,"method":"tools/list"}' | conceptio mcp

Windows PowerShell 的特殊情况： pwsh 会以 UTF-16 将文本通过管道传递给原生命令， 而服务端（UTF-8 JSON-RPC）会对此返回 Parse error。实际的 MCP 宿主使用 UTF-8，不受影响——这只会影响从 pwsh 执行手动编写的 echo ... | conceptio mcp 探测。请先将请求保存为 UTF-8：

'{"jsonrpc":"2.0","id":1,"method":"tools/list"}' | Out-File -Encoding utf8 req.jsonl
cmd /c "conceptio mcp < req.jsonl"

---

公平使用

Conceptio 中的所有来源均为开放访问或公有领域。CLI 会在每次请求中发送 你的 API 密钥，并按套餐等级限制速率（参见 速率限制）；浏览器提供 单独的免费试用，可供用户无需账户进行随意搜索。

使用 conceptio auth <key> 添加凭据一次——凭据会存储在 ~/.conceptio/config.json 中，并随每次请求发送。conceptio auth 接受自托管 API 密钥（ckey_live_...，从你的账户签发的 Agent／机器凭据——以明文存储；服务端会对其进行哈希处理，且只显示一次）， 或 Pro 许可证密钥 （CONCEPTIO-XXXX-XXXX-XXXX，一次性／与账户绑定）。API 密钥使用 X-Api-Key；许可证密钥使用 X-License-Key；每次只会发送一种凭据。

如果没有已保存的密钥，所有数据命令都会在访问网络前退出：

Authentication required — save an API key before searching.

conceptio quota 会报告你当前的套餐等级（public／pro／ enterprise）以及服务端认可的身份验证方式（api_key／license／ firebase／public）；conceptio quota --json 会返回相同报告的结构化对象， 供状态界面呈现，并将人类可读的凭据提示写入 stderr，以确保 stdout 保持可解析。

---

配置

状态保存在 ~/.conceptio/config.json 中：

{
  "api_base": "https://www.conceptio.app",
  "license_key": "",
  "api_key": "",
  "default_limit": 10,
  "default_citation_format": "bibtex"
}

编辑 api_base 可覆盖 API 基础地址（用于暂存环境、自托管镜像或本地代理）。 公共 API 来源必须使用 HTTPS；本地开发仅允许使用环回 HTTP 来源，例如 http://127.0.0.1:8000。客户端会拒绝跨来源的 API 重定向，以免凭据被发送到 意外的主机。PDF 下载会拒绝环回／专用网络目标，将响应大小限制为 100 MiB，并以原子方式写入。MCP 服务还会确保 output_path 位于当前工作区内，并拒绝路径遍历或符号链接逃逸。设置 default_limit 可更改搜索页大小；设置 default_citation_format 可选择 11 种受支持的格式名称之一。

宿主进程（编辑器、CI、Agent 运行时）可以在不写入配置文件的情况下提供凭据——环境变量的优先级高于已保存的值： CONCEPTIO_API_KEY、CONCEPTIO_LICENSE_KEY 和 CONCEPTIO_API_BASE。已登录用户的会话也可以按运行提供 CONCEPTIO_BEARER_TOKEN（与 Web 应用使用的短期 bearer 令牌相同）； 它的优先级高于机器密钥，且每次始终只会发送一种凭据。

开发

pip install -e ".[test]"     # or: pip install -e . && pip install pytest
pytest tests/                      # offline tests (mocked HTTP, no network)
python tests/live_check.py         # live: the real CLI against a loopback stub
python tests/live_prod_check.py --yes   # smoke: the real CLI against the real API

离线测试套件通过 MockTransport 为 httpx 打补丁，并在组合其他服务时模拟 ConceptioClient。其中没有任何测试会发起真实网络调用——这也是它的局限：它可以验证客户端是否组合了请求并解析了响应，却无法验证 CLI 在实时交互中会做出什么决定。

tests/live_check.py 弥补了这一不足。它会启动共享的环回存根（conceptio-nvim/test/stub_api.py，可切换为 done/running/expired 任务模式以及 exhausted/pro/not_configured 连接器模式），通过 CONCEPTIO_API_BASE 和环境凭据让真实二进制连接到该存根，并检查退出码、标准输出和存根的请求日志。它覆盖了完整功能面，而非抽样测试——搜索（指令、筛选条件、Markdown、批处理、任务）、解析、引用、信息、证明、下载的边界行为、凭据路径、连接器失败原因、全部九个 MCP 工具，以及每个编辑器客户端发送的确切 argv（见下文）。它还会拒绝悄悄地对错误的二进制运行：如果 conceptio --version 与此代码树声明的版本不符，那么所有检查验证的都会是旧版本安装，因此测试会失败并说明原因。

所有操作都在环回环境中进行：不需要账户、密钥或生产环境额度；CLI 使用临时配置目录，因此绝不会读取或写入你的真实 ~/.conceptio/config.json。CONCEPTIO_CLI 用于选择二进制，CONCEPTIO_STUB 用于选择存根，CONCEPTIO_LIVE_VERBOSE=1 会回显每条命令的输出。测试会以非零状态码退出，并输出每项失败检查及其对应命令的输出。

tests/live_prod_check.py 则刻意与该测试框架相反，而这两者正好互为补充。以上所有测试都针对我们控制的服务，因此无法发现实时 API 的变化——例如 /api/me 中的字段改名、拒绝消息措辞变化，或开始拒绝 CLI 传输方式的边缘规则。这些变化会悄无声息地发布，因为本仓库自身的测试套件仍然全绿，而每位真实用户都能看到这些偏差。

该测试需要选择加入（--yes），并通过构造保证安全，而非依赖使用者自律：只有基础 URL 是随附的默认值、凭据是占位值（它会剥除任何继承的 CONCEPTIO_* 变量，并以占位值取代），才会运行；而且它只运行无需凭据且 API 允许执行的读取操作，以及预期结果为拒绝的命令——绝不会执行搜索。删除 rm -f 保护后，它就无法再区分生产环境和存根；将默认基础 URL 改向其他地址后，它的 9 项检查中有 6 项会失败，这正说明了这些检查确实有效。

客户端契约

CLI 也是随项目发布的客户端界面（Neovim 插件和 Obsidian 插件）的依赖项。它们通过 argv 列表执行此二进制并读取标准输出；除此之外，两者之间没有任何耦合，只有这套语法。tests/client_contract.py 记录了它们发起的每次调用及其来源文件：

• tests/test_cli_contract.py 会使用 cli.build_parser() 解析每一行；如果某个客户端的检出目录位于本仓库旁边，还会断言其源代码仍包含该行所声称的子命令和标志。
• tests/live_check.py 会在存根上使用真实二进制运行相同行。

如果你更改了子命令或标志，其中一项检查就会失败并指出客户端。客户端增加调用时，请添加相应行。

README 也是一个客户端。tests/test_readme_contract.py 会从上方代码块中提取每次调用，并使用相同的语法进行解析，因此，标志改名不会导致文档教人使用一个只会报用法错误的命令。管道、重定向等 Shell 结构会通过明确规则跳过，而不是靠异常处理；如果测试不再找到示例，就会失败——一个悄悄什么也匹配不到的提取器毫无证明作用。

---

许可证

MIT——详见 LICENSE。

属于 Conceptio Open Knowledge Archive 的一部分——拥有 500 多个持续更新的来源：arXiv、NIST、OWASP、CISA、PubMed/PMC、MIT OpenCourseWare、EUR-Lex、Project Gutenberg 等。