feat: add MCP services, CLI and HTTP reader

Author: rockyshi1993

.github/workflows/ci.yml

@@ -34,6 +34,9 @@ jobs:
       - run: npm ci
       - run: npm test
       - run: npm run test:package:built
+      - run: npm run test:consumers:built
+      - run: npm run test:install:built
+      - run: npm run test:integration:built
       - run: npm ci --ignore-scripts
         working-directory: examples/seed-mcp
       - run: npm test

CONTRIBUTING.md

@@ -63,7 +63,7 @@ npm run check:examples
 
 最终验收在 `website` 按 build → check:build → test:site → check:build/check:package 执行，记录最终 doc_build 全部文件 SHA；浏览器预览不得隐式重建。之后若页面/配置/生成输入或输出变化，必须重建并重验同一制品。Playwright 管理自己的 preview，结束确认端口释放，不复用或杀用户服务。自动检查不替代独立用户走读，未取得真实走读证据时仍为 UNVERIFIED。
 
-MCP 完整 Server/Client 由公开页面还原到仓库同级临时消费者，安装固定 SDK 和本次构建的主包 tarball，保留 Seed 相对路径，标准 stdio 测试核对主入口无首轮泄漏、修订/参数/文档错误和进程退出。Registry 验证另安装已发布包，两种证据分别记录。原 Seed 11 个查询工具/五能力平坦 Catalog 回归不可替换。新增验证消费者必须同步页面、状态数据、helper、安装链、生成输出和测试，不只改截图断言。
+MCP 完整 Server/Client 由公开页面还原到仓库同级临时消费者，安装固定 SDK 和本次构建的主包 tarball，保留 Seed 相对路径，标准 stdio 测试核对主入口无首轮泄漏、修订/参数/文档错误和进程退出。Registry 验证另安装已发布包，两种证据分别记录。Seed 复用共享层的 12 个查询工具，五能力平坦 Catalog 回归仍保留；五工具渐进宿主另行验证。新增接入页由 `check-mcp-integration.mjs` 直接执行页面代码，覆盖普通JSON、SDKv1/v2、HTTP和Reader。新增验证消费者必须同步页面、状态数据、helper、安装链、生成输出和测试，不只改截图断言。
 
 ## 仅文档部署
 

README.md

@@ -11,7 +11,40 @@ npm view @devcodex/capability-graph@2.0.0 version
 npm install @devcodex/capability-graph@2.0.0
 ```
 
-Node.js：`^20.19.0 || >=22.12.0`。主包只有 ESM 根入口，包含 TypeScript 类型；固定依赖仅为 BCP 47 解析器与语言注册表。2.0 移除了数据库权威来源、能力召回、知识检索和 Runtime，升级前查看[2.0 迁移清单](https://github.com/devcodex-labs/capability-graph/blob/main/changelogs/2.0.0.md)。已发布的 1.1.0 与其 tag 保留原有接口。
+Node.js：`^20.19.0 || >=22.12.0`。ESM 与 TypeScript 类型覆盖根 SDK、`/mcp`、`/mcp/server`、`/readers/http` 四个入口；CLI 名称为 `capability-graph`。根 SDK 导入不会启动服务或注册配置。2.0 移除了数据库权威来源、能力召回、知识检索和 Runtime，升级前查看[2.0 迁移清单](https://github.com/devcodex-labs/capability-graph/blob/main/changelogs/2.0.0.md)。已发布的 1.1.0 与其 tag 保留原有接口。
+
+## 目录导航
+
+- [当前版本与安装](#当前版本与安装)
+- [最小接入](#最小接入)
+- [MCP工具、服务与CLI](#mcp工具服务与cli)
+- [能做什么](#能做什么)
+- [职责边界](#职责边界)
+- [示例、验证与维护](#示例验证与维护)
+
+## MCP工具、服务与CLI
+
+以下能力对应本次源码与本地打包制品，使用 Registry 前核验确切版本及子入口。未发布时，在当前对应源码根运行 `npm ci`、`npm pack --pack-destination ../packages`，安装本次生成的 tgz；公开站和源码不会自动发布。
+
+| 方式 | 入口与资源归属 |
+|---|---|
+| 普通JSON / 自有模型宿主 | `/mcp` 的 `createCapabilityGraphToolkit(graph)`；12个冻结JSON Schema，宿主决定调用流程，借用graph |
+| SDK v1/v2内嵌 | 同一toolkit分别接低层Server或McpServer.registerTool；可合并Provider自有工具和渐进发现 |
+| 独立stdio/HTTP | `/mcp/server` 的 `createCapabilityGraphServer`；默认127.0.0.1:3333/mcp，借用graph，调用方负责关闭Reader/graph |
+| 全局CLI | `serve/provider/codex/doctor/assist`；服务配置增删下次启动生效 |
+| HTTP文档 | `/readers/http` 的 `HttpKnowledgeReader`；精确Origin、UTF-8字节、取消和可选快照，宿主关闭Reader及自己的Agent |
+
+默认账户配置为 `~/.capability-graph/config.json`，最小内容 `{"schemaVersion":1,"providers":[]}`；`--config`可显式选择文件。下面命令以已有本地打包制品为前提：
+
+```sh
+npm install -g ./packages/devcodex-capability-graph-2.0.0.tgz
+capability-graph provider add --id acme.http --root /absolute/path/providers/acme-http --layout directory
+capability-graph doctor --json
+```
+
+第一条只有在能证明正常直接全局安装时自动注册stdio并完成临时协议探针；不会创建虚构Provider。`--ignore-scripts`、本地/依赖安装或无法证明直接目标时，可运行 `capability-graph codex register`。`provider add --root`填写你实际的目录，示例路径需替换；Provider ID须与该目录的provider.json一致。添加配置后重新启动服务。
+
+诊断分别返回 `installed/configRegistered/localProtocolVerified/clientConnected`；临时探针通过后，外部Codex客户端连接仍可为`unknown`。完整示例、变量来源、配置默认值与排错见[MCP与CLI接入](https://devcodex-labs.github.io/capability-graph/integrations/mcp-and-cli)。卸载前运行 `capability-graph codex unregister`，再 `npm uninstall -g @devcodex/capability-graph`；Provider资料和配置保留。
 
 ## 最小接入
 
@@ -96,19 +129,21 @@ try {
 
 能力图谱负责声明与查询。能力执行、Agent 意图判断、业务项目状态、RAG 的分块索引/Embedding/数据库/排名以及回答生成由宿主或独立模块负责。这里的文档分页是原文访问，不是知识检索。未来 RAG 可以使用公开能力身份、文档引用和分页接口，自行管理索引；主包不预留空检索框架。
 
-MCP 工具名称、认证与协议属于接入项目；主包没有 MCP 子入口。自定义 Reader 是进程内受信任代码，Provider scope 不是执行沙箱。
+共享MCP工具层提供12个查询，独立服务处理协议、入站校验和请求生命周期。Provider可在自己的宿主合并工具、资源和渐进发现策略。自定义Reader是进程内受信任代码，Provider scope不隔离进程。
 
 ## 示例、验证与维护
 
 - [Seed API](https://github.com/devcodex-labs/capability-graph/tree/main/examples/seed-api)：图谱发现、选择、文档与规范的完整链路。
-- [Seed MCP](https://github.com/devcodex-labs/capability-graph/tree/main/examples/seed-mcp)：独立私有包，11 个查询工具及规范 Resource。
+- [Seed MCP](https://github.com/devcodex-labs/capability-graph/tree/main/examples/seed-mcp)：SDK v1私有宿主，复用12个共享查询工具并保留Provider自有规范Resource。
 - [HTTP Reader](https://github.com/devcodex-labs/capability-graph/tree/main/examples/http-reader)：真实 HTTP、原字节分页、ETag、取消和资源清理。
 - [VextJS](https://github.com/devcodex-labs/capability-graph/tree/main/examples/vextjs)：固定来源的官方文档主题、安装包及 URL 读取；验证说明与实际执行范围一致。
 
 ```sh
 npm ci
 npm test
 npm run test:package
+npm run test:consumers
+npm run test:install
 npm run evaluate
 npm run demo:http
 npm run evaluate:capacity

examples/http-reader/README.md

@@ -2,6 +2,14 @@
 
 运行 `npm run demo:http`，从真实本地 HTTP 服务分页读取关联文档，并核对完整 UTF-8 原字节。示例不会启动能力执行服务。
 
-`knowledge-reader.ts` 是宿主可参考的 Reader 实现，不是主包导出。URL 来源必须配置明确的允许 origin。它支持超时、并发限制、流式取消，以及可选的强 ETag 磁盘快照和已验证范围读取；弱 ETag、无验证器、超出缓存预算时回退到完整扫描，文档仍可分页读取。
+`knowledge-reader.ts`消费主包`/readers/http`导出的同一实现。URL来源必须配置明确Origin。它支持超时、并发限制、四正文接口取消，以及可选强ETag磁盘快照与已验证范围读取；弱ETag、无验证器或超缓存预算时回退完整扫描，文档仍可分页读取。
+
+## 目录导航
+
+- [运行与参数](#运行与参数)
+
+## 运行与参数
+
+`allowedOrigins`必填且非空，要求精确http/https原点；timeoutMs默认2000毫秒，maxConcurrent默认4。snapshot可省略；启用时maxBytes默认16777216、maxEntries默认8、ttlMs默认300000。完整解释与独立消费代码见[接入教程](https://devcodex-labs.github.io/capability-graph/integrations/mcp-and-cli#6-http-reader)。
 
 可选 `snapshot.directory` 必须由宿主提供绝对路径并放在源码仓库之外。宿主负责关闭 Reader 和自己创建的 Agent；关闭图谱不会代替关闭这些资源。HTTP 错误、正文变化及无效 Range/验证器都显式失败。