AI导哈

文档服务器

一个基于TypeScript的模型上下文协议（MCP）服务器，通过工具和资源将多个本地文档文件夹（命名空间）暴露给AI助手。

  • by JWears
  • TypeScript
  • 本地部署
  • 更新于
在 GitHub 查看 JWears/Mcp-server

使用说明

本地文档MCP服务器

基于TypeScript的模型上下文协议（MCP）服务器，通过工具和资源向AI助手公开多个本地文档文件夹（命名空间）。

特性

  • 🔌 HTTP传输：在上使用流式HTTP POST /mcp （无标准）
  • 📁 多命名空间支持：使用命名空间隔离跨多个根组织文档
  • 🔗 资源访问：动态资源模板 docs://{namespace}/{path} 用于文件访问
  • 🛠️ 三个工具:
    • list_files -列出跨命名空间匹配glob模式的文件
    • read_file -从命名空间读取特定文件内容
    • search -在多个文件和命名空间中搜索文本
  • 🔒 安全：路径遍历预防、符号链接转义检测、二进制文件过滤、可配置的文件大小限制
  • 📝 MIME类型：自动检测所有文件的MIME类型
  • ⚙️ 灵活的配置：通过环境变量进行配置或 docs.config.json

安装

依赖项已安装。如果需要重新安装：

npm install

配置

方法1：配置文件(docs.config.json)

创建一个 docs.config.json 项目根目录中的文件：

{
  "roots": [
    {
      "ns": "docs",
      "path": "./docs"
    },
    {
      "ns": "api",
      "path": "./api-docs"
    },
    {
      "ns": "guides",
      "path": "C:/absolute/path/to/guides"
    }
  ],
  "maxFileKB": 256,
  "allowSymlinks": false,
  "ignore": [
    "**/node_modules/**",
    "**/.git/**",
    "**/dist/**",
    "**/build/**"
  ]
}

方法2：环境变量

设置 DOCS_DIRS 命名空间以逗号分隔的环境变量：路径对：

# Windows PowerShell
$env:DOCS_DIRS="docs:./docs,api:./api-docs,guides:C:/path/to/guides"
npm run dev

注： 环境变量优先，并将覆盖/合并 docs.config.json.

配置选项

  • roots：命名空间定义数组
    • ns：命名空间标识符（字母数字、连字符、下划线）
    • path：根目录的绝对或相对路径
  • maxFileKB：最大文件大小（KB）（默认值：256）
  • allowSymlinks：允许指向命名空间之外的符号链接（默认值：false）
  • ignore：要忽略的Glob模式（默认值：node_modules、.git等）
  • PORT：通过环境变量连接服务器端口（默认值：3000）

运行服务器

开发模式（带自动重新加载）

npm run dev

生产模式

npm start

服务器将在启动时打印MCP URL：

🚀 Local Docs MCP Server running
📁 Registered namespaces:
   - docs: C:\Users\...\mcp-day\docs
   - api: C:\Users\...\mcp-day\api-docs
🔗 MCP URL: http://localhost:3000/mcp
💚 Health check: http://localhost:3000/health

MCP检验员测试

  1. 安装MCP检查器 （如果尚未安装）：

    npx @modelcontextprotocol/inspector

  2. 启动服务器 在一个终端中：

    npm run dev

  3. 打开MCP检查器 在另一个终端中：

    npx @modelcontextprotocol/inspector

  4. 连接到服务器:

    • 在检查器UI中，输入MCP URL： http://localhost:3000/mcp
    • 运输类型： HTTP

  5. 测试工具:

    列出文件（所有命名空间）：

    {
  "pattern": "**/*.md",
  "max": 50
}

    列出文件（特定命名空间）：

    {
  "pattern": "**/*.md",
  "ns": "docs",
  "max": 50
}

    列出文件（多个命名空间）：

    {
  "pattern": "**/*.md",
  "ns": ["docs", "api"],
  "max": 50
}

    读取文件：

    {
  "ns": "docs",
  "path": "welcome.md"
}

    搜索（所有命名空间）：

    {
  "query": "MCP",
  "glob": "**/*.md",
  "max": 100
}

    搜索（特定命名空间）：

    {
  "query": "MCP",
  "glob": "**/*.md",
  "ns": "docs",
  "max": 100
}

  6. 测试资源:

    • 资源现在使用命名空间URI： docs://{namespace}/{path}
    • 例子： docs://docs/welcome.md, docs://api/endpoints.md
    • 点击检查器中的任何资源链接
    • 文件内容应显示正确的MIME类型

项目结构

mcp-day/
├── server.ts              # Main MCP server implementation
├── src/
│   └── roots.ts          # RootRegistry implementation
├── package.json          # Project configuration
├── tsconfig.json         # TypeScript configuration
├── docs.config.json      # Namespace configuration
├── README.md            # This file
└── docs/                # Default documentation namespace
    ├── welcome.md       # Sample markdown file
    ├── api.md           # API reference
    └── config.json      # Sample JSON file

工具参考

列表文件

列出文档目录中与glob模式匹配的文件。可以按命名空间进行筛选。

输入：

  • pattern （可选）：球形图案（默认值： **/*.{md,mdx,txt,json})
  • ns （可选）：要搜索的命名空间-字符串或数组。如果省略，则搜索所有命名空间
  • max （可选）：最大结果（默认值：200）

输出：

  • count：返回的文件数
  • namespaces：搜索的命名空间数组
  • files：数组 ns, path, uri, size, mtime, mimeType
  • 每个文件的资源链接为 docs://{ns}/{path}

read_file

从docs目录中的特定命名空间读取文件。

输入：

  • ns （必需）：要读取的命名空间
  • path （必需）：命名空间中文件的相对路径

输出：

  • ns：命名空间
  • path：文件路径
  • bytes：文件大小
  • lines：行数
  • 指向文件内容的资源链接为 docs://{ns}/{path}

搜索

在文件中搜索文本。可以按命名空间进行筛选。

输入：

  • query （必填）：搜索文本
  • glob （可选）：要搜索的文件模式
  • ns （可选）：要搜索的命名空间-字符串或数组。如果省略，则搜索所有命名空间
  • max （可选）：最大匹配数（默认值：100）
  • contextLines （可选）：上下文行（默认值：1）

输出：

  • query：搜索词
  • namespaces：搜索的命名空间数组
  • matchCount：比赛次数
  • matches：数组 ns, path, lineNumber, line, start, end, uri
  • 资源链接到匹配的文件，如 docs://{ns}/{path}

资源

服务器为每个命名空间公开动态资源模板：

  • URI模式: docs://{namespace}/{path}
  • 例子:
    • docs://docs/welcome.md
    • docs://api/endpoints.md
    • docs://guides/tutorial.md
  • 退货：具有正确MIME类型的文件内容

资源在工具响应中自动链接，可以直接在MCP检查器中打开。

安全特性

  1. 路径横向保护：所有路径都经过验证，以确保它们位于命名空间根目录内
  2. Symlink逃逸检测：默认情况下，指向命名空间外的符号链接被阻止（可配置）
  3. 二进制文件拒绝：二进制文件会自动跳过
  4. 可配置的文件大小限制：大于配置限制的文件将被拒绝（默认值：256KB）
  5. 命名空间验证：命名空间标识符已验证（仅限字母数字、连字符、下划线）
  6. 忽略模式：自动跳过node_modules、.git和其他配置的模式
  7. 山宁泰错误：错误消息不公开内部路径

定制

使用多个命名空间

示例1：通过环境变量

# Windows PowerShell
$env:DOCS_DIRS="docs:./docs,api:./api-docs,guides:C:/guides"
npm run dev

示例2：通过docs.config.json

{
  "roots": [
    { "ns": "docs", "path": "./docs" },
    { "ns": "api", "path": "./api-docs" },
    { "ns": "guides", "path": "C:/absolute/path/to/guides" }
  ]
}

要添加新的命名空间，请编辑 docs.config.json 文件并重新启动服务器。

配置文件大小限制

编辑 docs.config.json:

{
  "maxFileKB": 512,
  "roots": [...]
}

允许Symlinks

编辑 docs.config.json:

{
  "allowSymlinks": true,
  "roots": [...]
}

警告： 仅当您信任符号链接目标时才启用。这允许符号链接指向命名空间根之外。

自定义忽略模式

编辑 docs.config.json:

{
  "ignore": [
    "**/node_modules/**",
    "**/.git/**",
    "**/dist/**",
    "**/build/**",
    "**/*.log",
    "**/tmp/**"
  ],
  "roots": [...]
}

故障排除

服务器无法启动：

  • 检查端口3000是否已在使用中
  • 尝试其他端口： $env:PORT="3001"; npm start
  • 检查TypeScript编译错误

未显示的文件：

  • 验证中的命名空间配置 docs.config.json 或 DOCS_DIRS
  • 检查命名空间路径是否存在并且可访问
  • 确保文件与glob模式匹配
  • 检查文件权限
  • 查看忽略模式

未找到命名空间错误：

  • 跑 roots.list 查看已注册命名空间的工具
  • 检查命名空间拼写（区分大小写）
  • 验证 docs.config.json 是有效的JSON
  • 检查控制台日志中的初始化警告

检查员无法连接：

  • 验证服务器是否正在运行
  • 检查MCP URL是否正确： http://localhost:3000/mcp
  • 确保没有防火墙阻止连接
  • 检查运行状况端点： http://localhost:3000/health

路径遍历或符号链接错误：

  • 确保路径相对于命名空间根
  • 检查 allowSymlinks 设置是否使用符号链接
  • 验证符号链接没有逃逸命名空间目录

文件太大错误：

  • 增加 maxFileKB 在 docs.config.json
  • 或者使用忽略模式过滤掉大文件

许可证

国际学生委员会

相关 MCP