AI导哈

AI文档服务器

为AI代理提供CS2插件框架SwiftlyS2的文档访问服务，支持搜索、浏览和引用API。

  • by sak0a
  • JavaScript
  • 混合部署
  • 1 星标
  • 更新于
在 GitHub 查看 sak0a/swiftlys2-mcp-server

使用说明

SwiftlyS2 MCP服务器

MCP服务器，为AI代理提供访问 快速S2 文档——CS2（反恐精英2）插件框架。使Claude等人工智能工具在帮助您创建插件时能够搜索、浏览和引用SwiftlyS2 API。

特性

  • 6工具 — search_docs, get_api_reference, list_apis, get_code_examples, get_related_pages, get_cache_status
  • 资源 --直接URI访问任何文档页面(swiftlys2://docs/*)
  • 3提示 --创建插件、调试和学习API的指导工作流程
  • 两次运输 --本地stdio用于直接使用，HTTP（流式HTTP）用于远程托管
  • 持久磁盘缓存 --重启时立即从保存的文档中加载，每10分钟进行一次智能增量更新
  • 自动爬行 swiftlys2.net关于使用内存缓存启动的文档

快速入门（本地）

git clone https://github.com/yourusername/swiftlys2-mcp-server.git
cd swiftlys2-mcp-server
npm install
node src/server-http.js

验证： curl http://localhost:3000/health

设置：Coolify部署

  1. 将此仓库推送到GitHub/GitLab
  2. 在Coolify仪表板中，单击 +新资源 → 公共仓库
  3. 粘贴你的Git URL——Coolify自动检测Dockerfile
  4. 设置您的域名（例如。 swiftlys2-mcp.yourdomain.com)
  5. 点击 部署 --SSL是通过Let’s Encrypt自动实现的
  6. 验证： curl https://swiftlys2-mcp.yourdomain.com/health

设置：Docker/Docker Compose

# Docker
docker build -t swiftlys2-mcp .
docker run -d -p 3000:3000 -v swiftlys2-cache:/app/.cache --restart unless-stopped swiftlys2-mcp

# Docker Compose
docker compose up -d

设置：本地开发

npm install

# HTTP server (remote clients)
node src/server-http.js

# Stdio server (local MCP clients)
node src/server-stdio.js

客户端配置

Claude Code（远程HTTP服务器）

claude mcp add --transport http swiftlys2-docs https://swiftlys2-mcp.yourdomain.com/mcp

或本地：

claude mcp add --transport http swiftlys2-docs http://localhost:3000/mcp

克劳德代码（本地标准）

claude mcp add swiftlys2-docs -- node /absolute/path/to/swiftlys2-mcp-server/src/server-stdio.js

克劳德桌面

添加到您的 claude_desktop_config.json:

远程（流式HTTP）：

{
  "mcpServers": {
    "swiftlys2-docs": {
      "url": "https://swiftlys2-mcp.yourdomain.com/mcp"
    }
  }
}

本地（stdio）：

{
  "mcpServers": {
    "swiftlys2-docs": {
      "command": "node",
      "args": ["/absolute/path/to/swiftlys2-mcp-server/src/server-stdio.js"]
    }
  }
}

通用MCP客户端

HTTP服务器公开了一个可流式传输的HTTP端点：

方法 路径 目的
POST /mcp 主请求/响应+可选SSE流
GET /mcp 服务器发起的通知的SSE流
DELETE /mcp 会话终止
GET /health 健康检查({"status":"healthy"})

会话通过以下方式跟踪 mcp-session-id 头球

环境变量

变量 默认值 描述
PORT 3000 HTTP服务器端口
SWIFTLYS2_CACHE_PATH .cache/docs-cache.json 持久磁盘缓存文件的路径
SWIFTLYS2_UPDATE_INTERVAL 600 增量更新检查之间的秒数（默认10分钟）

缓存行为

服务器使用两层缓存策略：

  1. 内存缓存 --所有页面都存储在内存中，以便快速访问
  2. 磁盘缓存 --重启后仍能保存的JSON文件

启动流程：

  1. 从磁盘缓存加载（如果可用）→ 服务器立即可用
  2. 如果磁盘缓存是新的（<1小时）：在后台运行增量更新
  3. 如果磁盘缓存已过时/丢失：运行full fetch，然后保存到磁盘
  4. 定期更新每10分钟运行一次（可配置）

增量更新：

  • 重新发现当前页面路径（仅获取2个索引页面）
  • 检测新页面和已删除页面
  • 使用条件HTTP请求抽查约50个现有页面（ETag/If Modified Since）
  • 优先考虑高优先级类别（开发、指南）和最旧的提取页面

关机时（信号情报）： 缓存被保存到磁盘，以便立即重新启动。

API 参考

工具

search_docs --按关键字搜索文档

参数 类型 必填 说明
query string yes 搜索关键字
category string no 按类别筛选（例如。 api/commands)
limit number no 最大结果数（默认值10）

get_api_reference --获取整页内容

参数 类型 必填 说明
path string yes 文档路径（例如。 api/commands/command)

list_apis --列出可用的文档页面

参数 类型 必填 说明
category string 否 按类别筛选

get_code_examples --从文档中提取代码示例

参数 类型 必填 说明
path string no 要提取的特定页面路径
query string no 搜索包含代码示例的页面
language string no 按语言筛选（例如。 csharp, cpp)
limit number no 最大示例数（默认值5）

get_related_pages --查找相关文档页面

参数 类型 必填 说明
path string yes 查找相关页面的页面
limit number no 最大结果数（默认值10）

get_cache_status --关于缓存的诊断信息

参数 类型 必填 说明
（无） -- -- 返回总页数、类别和状态

资源

  • swiftlys2://docs/index --完整文档索引
  • swiftlys2://docs/api/{path} -个别API文件页

提示

  • create_plugin --引导插件创建（参数： pluginName, description)
  • debug_plugin --调试协助（参数： errorDescription, code?)
  • learn_api -API学习指南（参数： apiCategory)

使用示例

配置MCP客户端后：

"What APIs are available in SwiftlyS2?"
"Search SwiftlyS2 docs for creating menus"
"Get the Commands API reference"
"Help me create a plugin that gives health on kills"
"Debug my event hook — it's not firing"
"Show me code examples for database usage"
"What pages are related to the commands API?"
"What's the cache status?"

项目结构

swiftlys2-mcp-server/
├── src/
│   ├── lib/
│   │   ├── cache.js             # In-memory cache with TTL
│   │   ├── converter.js         # HTML-to-Markdown conversion
│   │   ├── disk-cache.js        # Persistent disk cache (load/save)
│   │   ├── fetcher.js           # Documentation crawler
│   │   ├── search.js            # Full-text search
│   │   └── update-scheduler.js  # Periodic background updates
│   ├── mcp/
│   │   ├── tools.js             # MCP tool definitions (6 tools)
│   │   ├── resources.js         # MCP resource definitions
│   │   ├── prompts.js           # MCP prompt definitions
│   │   └── server-factory.js    # Server assembly
│   ├── server-stdio.js          # Stdio entry point
│   └── server-http.js           # HTTP entry point
├── test/
│   └── test-server.js           # Automated tests
├── deploy-examples/
│   ├── nginx.conf
│   ├── Caddyfile
│   └── swiftlys2-mcp.service
├── Dockerfile
├── docker-compose.yml
└── package.json

故障排除

服务器已启动，但没有缓存文档： 服务器在启动时从swiftlys2.net获取文档。如果无法访问该网站，则不会缓存页面。检查网络连接和https://swiftlys2.net/docs/是可访问的。

Claude Code无法连接到HTTP服务器：

  • 验证服务器是否正在运行： curl http://localhost:3000/health
  • 检查您是否使用过 --transport http 添加服务器时
  • MCP端点为 /mcp，不 / 或 /sse

启动缓慢： 第一次运行时，服务器会抓取约100-400个页面。在后续运行中，它会立即从磁盘缓存中加载 .cache/docs-cache.json.Set SWIFTLYS2_CACHE_PATH 以自定义缓存位置。

Docker健康检查失败： 健康检查有60秒的开始时间，以便进行初始文档提取。如果仍然失败，请检查容器日志： docker logs <container>

缓存在Docker中不持久： 确保您使用的是卷装载 /app/.cache默认情况下，docker-compose.yml包含此内容。

许可证

麻省理工学院

相关 MCP