CompText MCP Server
使用说明（Markdown 格式）
- 项目简介
- CompText MCP Server 是一个用于 MCP（Model Context Protocol）的后端服务实现，旨在向 LLM 客户端提供统一的上下文资源、外部工具执行能力，以及可渲染的提示模板。服务器核心基于 MCP 规范实现工具注册、资源查询、命令执行等能力，并通过标准的 MCP 通道（如 STDIO）与客户端通信。数据源使用 Notion Codex，具备缓存、查询、分页解析等功能，同时提供简单的性能指标与速率限制。
- 主要功能点
- MCP 服务端核心功能：注册工具（Tools）、管理与执行命令、根据请求提供资源信息、响应 MCP JSON-RPC 风格的请求与结果。
- 数据源与资源管理：集成 Notion 客户端，提供获取所有模块、按模块查询、按标签/类型筛选、全文搜索等能力，并对结果进行结构化解析。
- 工具执行与格式化输出：实现多工具集合（如 list_modules、get_module、get_command、search、get_by_tag、get_by_type、get_statistics），并将输出格式化为文本或结构化内容，便于 LLM 处理。
- 缓存与重载：对 Codex 模块数据采用缓存，提供 clear_cache() 来强制刷新。
- 观测与限流：内置简单的性能指标收集、按端点限流，便于监控与调优。
- REST 辅助接口（可选）：提供 rest_api_wrapper.py，基于 FastAPI 的 HTTP/REST 接口，便于直接对外触达 Notion 数据与索引信息。对 MCP 客户端而言，核心通信仍通过 MCP 协议。
- 安装步骤
- 确保环境
- Python 3.10 及以上版本
- 依赖从 requirements.txt、requirements-dev.txt、requirements-rest.txt 等文件安装
- 环境变量：NOTION_API_TOKEN（Notion 访问令牌）、COMPTEXT_DATABASE_ID（Codex 数据库 ID，默认与常量一致）
- 安装与运行
- 获取代码后在项目根目录执行安装（可使用开发模式安装以便本地调试）
- 通过命令行启动 MCP 服务（MCP 客户端需要通过启动命令与参数与服务建立连接）：
- 使用内置的命令行入口：comptext-mcp
- 或直接运行 Python 模块：python -m comptext_mcp.server
- 运行后服务器通过标准输入输出与 MCP 客户端建立连接（stdio 模式是默认通信渠道之一，便于嵌入式/管道式集成）
- 可选：REST 网关
- 启动 REST API Wrapper（rest_api_wrapper.py）以便对外暴露 Notion 数据和工具状态，使用 uvicorn rest_api_wrapper:app 启动
- 服务器配置（MCP 客户端启动信息） { "server_name": "CompText MCP Server", "command": "comptext-mcp", "args": [] } 注解：
- server_name 为 MCP 客户端使用的名称标识，便于区分多实例部署。
- command 为启动 MCP 服务器的可执行命令（通过 CLI 提供的入口点，默认命令名为 comptext-mcp）。
- args 为启动参数列表，当前默认为空，若后续需要定制化启动参数可在此添加。
- 基本使用方法
- 启动后，LLM 客户端通过 MCP 协议与服务器建立会话，发送对资源、工具等的请求。
- 常用操作示例（由客户端向 MCP 服务器发起请求，LLM 侧处理）：
- 获取模块列表与摘要
- 按字母模块查询具体条目
- 读取特定页面内容命令
- 使用搜索功能在 Codex 中查找示例/文档
- 按标签或类型筛选条目
- 获取数据统计信息
- 服务器还提供性能指标、缓存清理等运维能力，便于监控与维护。
注意事项
- MCP 客户端需要通过命令启动服务器并建立标准输入输出的通信通道。
- 运行时需确保 Notion API Token 与 Codex 数据库 ID 配置正确，若未设置令牌则相关 Notion API 调用会在测试环境中被模拟或通过 Mock 进行测试。
- REST 接口仅为辅助用途，MCP 交互核心在于 stdio(或其他 MCP 传输方式)。