AI导哈

文档语义搜索服务

通过模型上下文协议（MCP）对GMAT文档进行语义搜索的服务，支持MCP兼容客户端查询。

  • by NachoG2000
  • TypeScript
  • 本地部署
  • 更新于
在 GitHub 查看 nachog2000/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

许可证

国际协调委员会

相关 MCP