Gmat Docs MCP Server

GMAT Docs MCP服务器

通过模型上下文协议（MCP）对GMAT文档进行语义搜索。该服务器抓取、解析、嵌入和缓存GMAT文档，以便任何兼容MCP的客户端（例如Cursor、Claude Desktop、自定义应用程序）都可以使用 searchDocs 工具。

特性

• searchDocs工具：使用OpenAI嵌入进行语义搜索
• 本地缓存：嵌入存储在 data/embeddings.json
• 确定性管道：刮擦→ 解析/组块→ 嵌入→ cache

需求

• Node.js 18+（ESM、OpenAI SDK v5）
• pnpm（项目用途 pnpm@10 每 package.json)
• 可访问的OpenAI API密钥 text-embedding-3-small

快速开始

1. 克隆仓库

git clone https://github.com/your-org/gmat-docs-mcp-server.git
cd gmat-docs-mcp-server

1. 安装依赖项

pnpm install

1. 配置环境

创建一个 .env.local （在运行时使用）和/或 .env （也由安装程序读取）repo根目录下的文件：

echo "OPENAI_API_KEY=your_api_key_here" > .env.local

您可以添加的可选变量（显示默认值）：

• CACHE_DIR （默认值： ./data)
• BASE_URL （默认值： https://documentation.help/gmat/)

1. 构建项目

pnpm build

1. 生成本地缓存（抓取、解析/块、嵌入）

pnpm run setup

这产生 data/embeddings.json （或 ${CACHE_DIR}/embeddings.json).

1. 启动MCP服务器

pnpm start

服务器在stdio上运行，并公开 searchDocs 工具到您的MCP客户端。

脚本

• pnpm构建：将TypeScript编译为 dist/
• pnpm启动：从以下位置运行服务器 dist/index.js （负载 .env.local)
• pnpm-dev：在监视模式下运行服务器 ts-node
• pnpm运行设置：从实时文档构建缓存（需要OpenAI API密钥）
• pnpm运行设置：测试：使用以下命令构建较小的测试缓存 pages-test.json

通过 --force 向 setup 从头开始重建缓存：

pnpm run setup -- --force

环境变量

• OPENAI_API密钥 （必填）：用于嵌入
• CACHE_DIR （可选）：目录 embeddings.json （默认值： ./data)
• BASE_URL （可选）：文档基URL（默认值： https://documentation.help/gmat/)
• NODE_ENV （可选）：设置为 test 使用 pages-test.json 在设置过程中
• MCP端口 （可选）：用于通过TCP/SSE公开此stdio服务器的包装器/适配器。此服务器本身通过stdio通信，不绑定到端口；某些客户端或适配器可能会读取 MCP_PORT 决定监听哪个端口。

读取文件以获取环境值：

• 安装程序读取两者 .env 和 .env.local
• 运行时读取 .env.local （通过 pnpm start)或者你的shell环境

与MCP客户端一起使用

此服务器通过stdio进行通信。指向MCP客户端以执行项目目录中的服务器。两种常见方法：

选项A：使用启动脚本

pnpm start

您的MCP客户端应在repo根目录中生成此命令（确保 .env.local 被拾起）。

选项B：使用包装器

有一个方便的包装器可以确保加载env，然后启动编译后的服务器：

node start-mcp.js

注意：如果您在通过SSE/TCP为MCP提供服务的适配器后面运行服务器，则可以设置 MCP_PORT 以引导该适配器。这里的服务器代码仍然通过stdio进行通信。

工具：searchDocs

输入：

• query （字符串，必填）
• topK （数字，默认10，1–50）
• minScore （数字，默认值0.1，0–1）

输出：带有页面名称、源URL、相似性评分和提取内容的格式化文本。

数据和缓存

• 缓存文件： data/embeddings.json （或 ${CACHE_DIR}/embeddings.json)
• 要重建，请执行以下操作： pnpm run setup -- --force
• 要使用较小的测试集： pnpm run setup:test

自定义页面

要抓取的页面列表在中定义：

• pages.json （全套）
• pages-test.json （较小的测试集）

您可以编辑这些文件以更改爬网范围。解析器试图通过标题提取有意义的部分，并将其转换为Markdown进行嵌入。

故障排除

• 错误：OPENAI_API_KEY环境变量是必需的

- 创建 .env.local （以及可选 .env)与 OPENAI_API_KEY

• 在data/embeddings.json中找不到缓存。先运行安装程序。

- 跑 pnpm build && pnpm run setup 生成缓存

• 抓取时网络超时

- 刮刀以指数回退重试；重播 setup 或调整您的网络

• MCP客户端看不到工具

- 确保服务器从项目目录启动并通过stdio连接 - 确认 pnpm start 日志显示服务器正在运行，缓存已加载

项目结构

src/
  index.ts        # MCP server entry (stdio)
  setup.ts        # Setup pipeline: scrape → parse/chunk → embed → cache
  tools/          # MCP tool definitions and handlers
  utils/          # scraper, parser, embedder, cache, search
data/             # Default cache directory (embeddings.json)
pages.json        # Full list of pages to scrape
pages-test.json   # Smaller list for testing
dist/             # Compiled JavaScript (after pnpm build)
start-mcp.js      # Wrapper to load env and run the server

许可证

国际协调委员会