Wotz Docs MCP Server

WotzDocs MCP服务器

基于Laravel的MCP（模型上下文协议）服务器，将私有GitHub存储库中的文档提供给AI助手。

特性

• GitHub集成：使用GitHub REST API从专用GitHub存储库获取文档
• MCP工具：提供用于列出包、搜索文档和获取内容的工具
• MCP资源：将文档作为具有适当URI的资源（例如。， docs://package/path/to/file.md)
• 缓存：智能缓存，最大限度地减少对GitHub的API调用
• 轻松的包管理：添加和管理文档包的简单技工命令

先决条件

• PHP 8.1+
• Laravel 10.0+
• 作曲家
• GitHub个人访问令牌（用于私有存储库）

安装

1. 克隆并设置项目：

   composer install
   cp .env.example .env
   php artisan key:generate

1. 配置您的环境：

编辑 .env 并添加您的GitHub令牌：

   GITHUB_TOKEN=your_github_personal_access_token

1. 运行迁移：

   php artisan migrate

1. 发布MCP配置（可选）：

   php artisan vendor:publish --provider="PhpMcp\Laravel\Server\McpServiceProvider" --tag="mcp-config"

添加文档包

使用 mcp:add-package 添加新文档源的命令：

php artisan mcp:add-package    [options]

示例：

# Add a package with default settings (docs in 'docs' folder, master branch)
php artisan mcp:add-package my-package myorg my-repo

php artisan mcp:add-package codedor/filament-architect codedor filament-architect

# Specify custom documentation path and branch
php artisan mcp:add-package my-package myorg my-repo --docs-path=documentation --branch=develop

# Add with description
php artisan mcp:add-package my-package myorg my-repo --description="Core API documentation"

列出所有包：

php artisan mcp:list-packages

运行MCP服务器

发展（STDIO运输）：

php artisan mcp:serve

生产（HTTP+SSE传输）：

配置您的web服务器以服务Laravel应用程序，然后访问：

http://your-domain.com/mcp/sse

MCP功能

工具

• list_packages：列出所有可用的文档包
• get_package_structure：获取包文档的文件结构
• search_docs：搜索所有文档（或特定文件包）
• refresh_package_docs：强制刷新缓存的文档

资源

• docs://index：主要文档索引（Markdown）
• docs://packages：包列表（JSON）
• docs://{package}/{path}：特定文档文件

AI助手中的示例用法：

# List available packages
Use tool: list_packages

# Get documentation structure
Use tool: get_package_structure with packageName="my-package"

# Search documentation
Use tool: search_docs with query="authentication"

# Read specific documentation
Get resource: docs://my-package/guide/getting-started.md

配置

缓存设置

在中配置缓存持续时间 .env:

MCP_DOCS_CACHE_TTL=3600  # Cache for 1 hour (in seconds)

发现路径

默认情况下，MCP元素位于 app/Mcp/。您可以在中对此进行自定义 config/mcp.php.

故障排除

未找到文档

• 验证GitHub存储库是否存在，以及是否可以使用您的令牌访问
• 检查一下 docs_path 是正确的
• 确保您的GitHub令牌具有适当的权限

缓存问题

# Clear MCP discovery cache
php artisan cache:clear

# Force refresh documentation for a package
php artisan mcp:serve
# Then use the refresh_package_docs tool

调试模式

启用调试登录 .env:

MCP_LOGGING_ENABLED=true
LOG_LEVEL=debug

安全

• 将您的GitHub令牌安全地存储在 .env
• 永不承诺 .env 到版本控制
• 使用适当的GitHub令牌范围（最低要求： repo 对于私有存储库）

高级用法

自定义文档处理器

您可以扩展 GitHubDocumentationService 要添加自定义处理，请执行以下操作：

1. 创建新的服务扩展 GitHubDocumentationService
2. 覆盖以下方法 fetchDocumentationContent 添加自定义处理
3. 将您的自定义服务绑定到服务提供商中

添加非GitHub源代码

该架构支持多种文档来源：

1. 创建实现相同接口的新服务
2. 更新 DocumentationServer 使用您的服务
3. 添加适当的配置选项

运行mcp服务器

运行http传输：

php artisan mcp:serve --transport=http

将此添加到claude代码中

claude mcp add --transport sse wotz-docs-mcp http://127.0.0.1:8090/mcp/sse