Spica MCP Server

Spica MCP服务器

用于与Spica实例交互的模型上下文协议（MCP）服务器。该服务器提供用于管理Spica中的存储桶、标识、策略、API密钥和函数的工具，并具有集成的文档搜索功能。

安装

适用于VS Code GitHub Copilot用户

先决条件:

• 已安装GitHub Copilot扩展
• MCP兼容扩展（在VS代码市场中搜索“MCP客户端”或“模型上下文协议”）

备注：VS Code中的MCP支持正在发展。不同的MCP扩展可能使用略有不同的配置格式。上述配置适用于大多数标准MCP客户端。

1. 安装MCP扩展：在VS代码中安装兼容的MCP扩展（如“MCP客户端”或类似）

1. 添加MCP服务器配置 到您的VS代码设置。打开您的VS代码设置（JSON）并添加：

{
  "mcp.servers": {
    "spica-mcp-server": {
      "command": "node",
      "args": ["/path/to/your/spica-mcp/dist/index.js"],
      "env": {
        "SPICA_URL": "http://localhost:4500",
        "SPICA_API_KEY": "YOUR_SPICA_API_KEY_HERE"
      }
    }
  }
}

使用npm的替代方法：

{
  "mcp.servers": {
    "spica-mcp-server": {
      "command": "npm",
      "args": ["run", "start"],
      "cwd": "/path/to/your/spica-mcp",
      "env": {
        "SPICA_URL": "http://localhost:4500",
        "SPICA_API_KEY": "YOUR_SPICA_API_KEY_HERE"
      }
    }
  }
}

适用于Claude桌面用户

将此配置添加到您的Claude Desktop配置文件中(claude_desktop_config.json):

{
  "mcpServers": {
    "spica-mcp-server": {
      "command": "/path/to/your/spica-mcp/start-mcp.sh",
      "env": {
        "SPICA_URL": "http://localhost:4500",
        "SPICA_API_KEY": "YOUR_SPICA_API_KEY_HERE"
      }
    }
  }
}

手动安装

git clone https://github.com/your-username/spica-mcp-server.git
cd spica-mcp-server
npm install
npm run build

设置

1. 复制示例设置:

   cp .vscode/settings.json

1. 编辑设置：更新 SPICA_URL 和 SPICA_API_KEY 在……里面 .vscode/settings.json

1. 安装推荐的扩展：VS Code会自动建议安装GitHub Copilot扩展

配置

服务器完全通过Claude Desktop配置中的环境变量进行配置：

必需变量（来自用户）

• SPICA_URL：您的Spica实例URL（例如。， http://localhost:4500)
• SPICA_API_KEY：您的Spica API密钥/令牌

预配置（无需用户设置）

• 内置文档搜索和人工智能答案

获取Spica API密钥

1. 打开您的Spica仪表板
2. 首选 护照 → API密钥
3. 创建具有所需权限的新API密钥
4. 复制密钥并将其用作 SPICA_API_KEY

配置文件位置

克劳德桌面

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• 视窗: %APPDATA%\Claude\claude_desktop_config.json
• Linux: ~/.config/claude/claude_desktop_config.json

VS代码

• 设置JSON：打开VS代码→ 偏好设置→ 设置→ 打开设置（JSON）
• 工作区设置: .vscode/settings.json 在项目根目录中（用于项目特定的配置）

如何使用

使用克劳德桌面

配置后，您可以在Claude中使用自然语言提示。服务器包括 文档优先工作流程 这鼓励在执行操作之前搜索文档。

使用VS代码GitHub副本

安装MCP扩展并配置服务器后，您可以：

1. 使用命令选项板(Cmd+Shift+P / Ctrl+Shift+P)访问MCP命令
2. 使用集成MCP工具的Copilot聊天
3. 直接从您的开发环境访问Spica管理工具

推荐工作流程

1. 始终从文档开始：使用 search 和 answer_question 工具
2. 然后执行操作：正确理解Spica工具

示例会话（Claude）：

Human: I want to create a new bucket for user profiles

Claude: I'll help you create a user profiles bucket. Let me first search the documentation to understand the proper structure and requirements.

[Uses search tool to find bucket documentation]
[Uses answer_question tool to get specific guidance]
[Then uses bucket-create tool with proper parameters]

示例会话（VS代码副本）：

// In VS Code, you can use Copilot Chat or MCP commands
// Example: Using Command Palette
1. Press Cmd+Shift+P (Mac) or Ctrl+Shift+P (Windows/Linux)
2. Type "MCP: Execute Tool"
3. Select "bucket-list" to see all buckets
4. Or use Copilot Chat: "@mcp create a user bucket with name, email, age fields"

示例提示：

1. 为我创建一个包含字段名称、电子邮件和年龄的测试桶

- 副驾驶将使用 bucket-create 工具

1. “列出我的所有水桶”

- 副驾驶将使用 bucket-list 工具

1. “添加一个名为'John Doe'的新用户，电子邮件为'john@example.com“，25岁”

- 副驾驶将使用 bucket-data-create 工具

1. “创建一个函数，为HTTP请求返回hello world”

- 副驾驶将使用 function-create 工具

1. “显示数据库中的所有用户”

- 副驾驶将使用 bucket-data-list 工具

可用工具

📚 文档和帮助

• help：获取设置指南和工作流程说明
• search：搜索API和功能的文档
• answer_question：从文档中获取AI驱动的答案
• fetch：检索文档元数据

🗂️ 桶管理（集合）

• bucket-list：列出所有桶
• bucket-create：创建新bucket
• bucket-update：更新现有bucket
• bucket-delete：删除bucket

📊 Bucket数据管理

• bucket-data-list：列出存储桶中的数据
• bucket-data-create：向bucket中添加新数据
• bucket-data-update：更新bucket中的现有数据
• bucket-data-delete：从bucket中删除数据

👥 身份管理（用户）

• passport-identity-list：列出所有身份
• passport-identity-get：获取特定身份
• passport-identity-create：创建新身份
• passport-identity-update：更新现有身份
• passport-identity-delete：删除身份
• passport-identity-verify：验证身份令牌
• passport-login：使用凭据登录

🔑 API密钥管理

• passport-apikey-list：列出所有API密钥
• passport-apikey-get：获取特定的API密钥
• passport-apikey-create：创建新的API密钥
• passport-apikey-update：更新现有的API密钥
• passport-apikey-delete：删除API密钥
• passport-apikey-assign-policy：将策略分配给API密钥
• passport-apikey-remove-policy：从API密钥中删除策略

🛡️ 策略管理（权限）

• passport-policy-list：列出所有政策
• passport-policy-get：获取具体政策
• passport-policy-create：创建新策略
• passport-policy-update：更新现有策略
• passport-policy-delete：删除策略

⚡ 功能管理

• function-list：列出所有功能

Claude使用示例

基本工作流示例：

1. 设置用户管理:

   Help me set up user management in Spica. I need to create user identities and manage permissions.

1. 创建博客系统:

   I want to create a blog system with posts and authors. Help me set up the buckets and data structure.

1. 管理API访问:

   I need to create API keys with different permission levels for my mobile app and admin panel.

⚠️ 重要提示：文件优先法

此MCP服务器旨在通过以下方式鼓励最佳实践 先搜索文档许多工具包括以下指导：

• 使用 search 操作前工具
• 使用 answer_question 理解正确的语法
• 在进行更改之前，验证API结构和要求

这可以防止错误，并确保您遵循当前的最佳实践。

故障排除

VS代码GitHub副本问题

1. MCP服务器未连接:

- 确保您安装了MCP兼容的扩展 - 检查settings.json中的服务器路径是否正确且绝对 - 更改MCP配置后重新启动VS代码 - 验证服务器构建是否成功： npm run build

1. 检查服务器状态:

- 跑 npm run dev 手动确保服务器无错误启动 - 检查VS代码开发人员控制台（帮助>切换开发人员工具）是否存在与MCP相关的错误

1. 扩展要求:

- 从VS Code市场安装“MCP客户端”或兼容的MCP扩展 - 确保GitHub Copilot扩展已安装并处于活动状态 - 检查两个扩展是否相互兼容

Claude桌面问题

1. MCP服务器未连接到Claude:

- 检查一下 start-mcp.sh 具有执行权限： chmod +x start-mcp.sh - 验证中的路径 claude_desktop_config.json 是正确的 - 配置更改后重新启动Claude Desktop

常见问题（两个平台）

• 身份验证错误：请确保您的Spica API密钥有效且未过期
• 网络问题：确保您的Spica实例正在运行且可访问
• 权限错误：验证您的API密钥是否具有存储桶和函数操作所需的权限
• 环境变量：仔细检查一下 SPICA_URL 和 SPICA_API_KEY 设置正确

运行服务器

npm run dev

服务器将启动并通过stdio监听MCP请求。