Stimulus Docs MCP 服务器

用于访问最新 Stimulus JS 文档的 MCP 服务器。Stimulus JS。

⚠️ 这是一个实验性软件

此 MCP 处于早期开发阶段。它可能包含错误、功能有限或未经通知的重大变更。请自行承担风险并预期潜在的不稳定。

构建 MCP 服务器

预备条件

• Node.js: 最低版本 18.0.0 或更高
• npm: 与 Node.js 捆绑在一起

构建指南

1. 克隆此仓库并导航到项目目录
2. 安装依赖项：

   npm install
   

3. 使用提供的脚本构建项目：

   npm run build
   

这将编译 TypeScript 源代码并在 build/ 目录中创建可执行文件。

使用方法

在 Claude Desktop 中使用

1. 首先，按照上述说明构建 MCP 服务器
2. 按照 https://modelcontextprotocol.io/quickstart/user 的说明添加新的 MCP 服务器。
3. 添加以下配置：

{
  "mcpServers": {
    "stimulus-docs": {
      "command": "node",
      "args": ["/path/to/your/stimulus-docs-mcp-server/build/index.js"],
      "env": {}
    }
  }
}

3. 将 /path/to/your/stimulus-docs-mcp-server 替换为此项目的实际路径
4. 重启 Claude Desktop
5. 现在，Stimulus 文档工具应在您的 Claude 对话中可用

在 VS Code 中使用

1. 按照上述说明构建 MCP 服务器
2. 按照 https://code.visualstudio.com/docs/copilot/chat/mcp-servers 的说明操作
3. 根据上述说明中的偏好方法，通过指向已构建的可执行文件来配置 MCP 服务器：

   {
    "stimulus-docs": {
        "type": "stdio",
        "command": "node",
        "args": [
            "path/to/your/stimulus-docs-mcp-server"
          ]
    }
   }
   

4. 将 path/to/your/stimulus-docs-m-服务器 替换为第 1 步中构建的 index.js 文件的路径。
5. 通过 MCP 客户端界面可以访问 Stimulus 文档

故障排除

Claude

在配置 MCP 后打开 Claude 时，可能会看到以下错误：

MCP stimulus-docs: spawn node ENOENT (2)

无法连接到 MCP 服务器 stimulus-docs

MCP stimulus-docs: 服务器断开连接。有关故障排除指导，请参阅 [...]

这是因为找不到 node 可执行文件的路径。如果是这种情况，而不是使用 "command": "node"，请使用完整的 node 路径。如果您使用的是 mise，可能是这样的：

"command": "/Users/<YOUR USER NAME/.local/share/mise/installs/node/20.18.3/bin/node

文档源及缓存策略

此 MCP 服务器直接从 GitHub 上的官方 stimulus-site 仓库 获取最新的 Stimulus 文档。为了确保最佳性能并减少 API 调用次数，服务器实现了以下缓存策略：

工作原理

1. 新鲜内容检测：服务器检查 GitHub 仓库中的最新提交 SHA 和时间戳
2. 缓存键生成：使用提交 SHA（前 7 个字符）和时间戳生成唯一的缓存键
3. 缓存：使用缓存键作为文件夹结构，将文档文件本地缓存
4. 缓存验证：在从 GitHub 获取之前，服务器检查当前提交的内容是否已经缓存
5. 回退策略：如果 GitHub 不可用，服务器会回退到本地文档文件

缓存结构

cache/
  {commit-sha}-{timestamp}/
    handbook/
      01_introduction.md
      02_hello_stimulus.md
      ...
    reference/
      actions.md
      targets.md
      ...

优点

• 始终最新：当 Stimulus 仓库发生变化时，内容会自动更新
• 性能：缓存内容加载迅速，无需网络请求
• 可靠性：本地回退确保即使 GitHub 不可用，服务器也能正常工作
• 高效：仅在仓库更新时获取新内容

src/docs/ 目录下的本地文档文件作为备份，确保 MCP 服务器即使没有互联网连接也能正常运行。

所有文档内容的功劳归于 Stimulus 团队及其贡献者。

可用工具

此 MCP 服务器提供了对完整的 Stimulus 文档的访问，组织如下：

手册：

• Stimulus 的起源
• 简介
• Hello Stimulus 教程
• 创建一些真实的东西
• 设计以抵御脆弱性
• 管理状态
• 使用外部资源
• 安装 Stimulus

参考：

• 动作
• 控制器
• CSS 类
• 生命周期回调
• 出口
• 目标
• 使用 TypeScript
• 值

每个文档部分都作为一个独立的工具提供，可以调用来检索相关内容。