Ghost MCP Server

🚀 幽灵安全MCP服务器

这是用于幽灵安全API的模型上下文协议（MCP）服务器，可通过标准化工具提供对安全检测结果和仓库数据的安全访问。

✨ 主要特性

• 安全检测结果管理：查询、检索和更新安全检测结果。
• 仓库分析：访问仓库数据及相关检测结果。
• 通用MCP兼容性：可与任何兼容MCP的客户端或应用程序配合使用。
• 内置CLI聊天机器人：包含一个简单的聊天机器人，便于快速交互。
• 全面的API覆盖：完全支持幽灵安全API（V2）端点。
• 类型安全：使用TypeScript完整实现，并具备正确的类型定义。
• 错误处理：拥有强大的错误处理和验证机制。

📦 安装指南

为Claude Code CLI快速安装

选项1：交互式安装程序（最简单）

# 克隆并构建
git clone https://github.com/ghostsecurity/ghost-mcp-server
cd ghost-mcp-server
npm install && npm run build

# 运行交互式安装程序（会提示输入API密钥）
npm run install:interactive

选项2：自动化设置脚本

# 克隆并构建
git clone https://github.com/ghostsecurity/ghost-mcp-server
cd ghost-mcp-server
npm install && npm run build

# 使用你的API密钥运行设置脚本
./setup-claude-code.sh YOUR_API_KEY

# 可选：指定特定仓库
./setup-claude-code.sh YOUR_API_KEY YOUR_REPO_ID

选项3：手动设置

# 克隆并构建
git clone https://github.com/ghostsecurity/ghost-mcp-server
cd ghost-mcp-server
npm install && npm run build

# 添加到Claude Code
claude mcp add --transport stdio --scope user ghost-security -- node $(pwd)/dist/index.js

# 然后编辑 ~/.claude.json 并在 mcpServers.ghost-security.env 下添加：
# {
#   "GHOST_SECURITY_API_KEY": "your-api-key",
#   "GHOST_SECURITY_BASE_URL": "https://api.ghostsecurity.ai/v2"
# }

选项4：从npm安装（即将推出） 一旦发布到npm，安装将更加简单：

claude mcp add --transport stdio --scope user ghost-security -- npx ghostsecurity-mcp

然后将你的API密钥添加到 ~/.claude.json：

{
  "mcpServers": {
    "ghost-security": {
      "env": {
        "GHOST_SECURITY_API_KEY": "your-api-key-here",
        "GHOST_SECURITY_BASE_URL": "https://api.ghostsecurity.ai/v2"
      }
    }
  }
}

标准安装（适用于所有MCP客户端）

1. 克隆此仓库：

git clone <repository-url>
cd ghost-mcp-server

2. 安装依赖项：

npm install

3. 构建项目：

npm run build

💻 使用示例

配置

服务器在启动时需要提供幽灵安全API密钥，你可以通过以下两种方式提供：

选项1：环境变量（推荐）

export GHOST_SECURITY_API_KEY="your-ghost-security-api-key"
export GHOST_SECURITY_BASE_URL="https://api.ghostsecurity.ai/v2"  # 可选，默认为v2
export GHOST_SECURITY_REPO_ID="your-repository-id"  # 可选 - 指定特定仓库

选项2：命令行参数

node dist/index.js "your-ghost-security-api-key" "your-repository-id"

注意：仓库ID是可选的。如果提供了仓库ID，所有操作都将限定在该仓库范围内。

运行服务器

开发环境：

# 首先设置环境变量
export GHOST_SECURITY_API_KEY="your-api-key"
npm run dev

生产环境：

# 使用环境变量
export GHOST_SECURITY_API_KEY="your-api-key"
npm start

# 或者使用命令行参数
npm run build
node dist/index.js "your-api-key"

CLI聊天机器人

本项目包含一个由Anthropic的Claude API驱动的简单CLI聊天机器人，可与MCP服务器进行交互。

export ANTHROPIC_API_KEY="your-anthropic-api-key"
export GHOST_SECURITY_API_KEY="your-ghost-api-key"
npm run chat

添加到任何MCP客户端

此服务器遵循标准的MCP配置格式。以下是不同客户端的配置示例：

标准MCP配置（Claude桌面版、ChatGPT等）

{
  "mcpServers": {
    "ghostsecurity": {
      "command": "node",
      "args": ["/path/to/ghost-mcp-server/dist/index.js"],
      "env": {
        "GHOST_SECURITY_API_KEY": "your-ghost-security-api-key",
        "GHOST_SECURITY_REPO_ID": "your-repository-id"
      }
    }
  }
}

环境变量设置（通用）

对于任何支持环境变量的MCP客户端：

export GHOST_SECURITY_API_KEY="your-ghost-security-api-key"
export GHOST_SECURITY_BASE_URL="https://api.ghostsecurity.ai/v2"
export GHOST_SECURITY_REPO_ID="your-repository-id"

仓库范围设置

当通过 GHOST_SECURITY_REPO_ID 环境变量或CLI参数配置了仓库ID时：

• ghostsecurity_get_findings 仅返回该仓库的检测结果。
• ghostsecurity_get_repositories 仅返回配置的仓库。
• ghostsecurity_get_repository_findings 默认使用配置的仓库（repoId参数可选）。

可用工具

安全检测结果

ghostsecurity_get_findings

获取安全检测结果，支持可选的过滤和分页。 参数：

• cursor（字符串，可选）：分页游标。
• sort（字符串，可选）：排序字段（created_at、updated_at）。
• order（字符串，可选）：排序顺序（asc、desc）。
• size（数字，可选）：每页大小（1 - 1000）。
• status（字符串，可选）：按状态过滤。
• repo_id（字符串，可选）：按仓库ID过滤。
• project_id（字符串，可选）：按项目ID过滤。

ghostsecurity_get_finding

通过ID获取特定的安全检测结果。 参数：

• id（字符串，必需）：检测结果ID。
• repoId（字符串，必需）：与检测结果关联的仓库ID。
• projectId（字符串，必需）：与检测结果关联的项目ID。

ghostsecurity_update_finding_status

更新安全检测结果的状态。 参数：

• id（字符串，必需）：检测结果ID。
• repoId（字符串，必需）：与检测结果关联的仓库ID。
• projectId（字符串，必需）：与检测结果关联的项目ID。
• status（字符串，必需）：检测结果的新状态。

仓库

ghostsecurity_get_repositories

获取仓库列表，支持可选的过滤和分页。 参数：

• cursor（字符串，可选）：分页游标。
• sort（字符串，可选）：排序字段（created_at、updated_at、last_committed_at）。
• order（字符串，可选）：排序顺序（asc、desc）。
• size（数字，可选）：每页大小（1 - 1000）。

ghostsecurity_get_repository

通过ID获取特定的仓库。 参数：

• id（字符串，必需）：仓库ID。

ghostsecurity_get_repository_findings

获取特定仓库的安全检测结果。 参数：

• repoId（字符串，可选*）：仓库ID（*除非配置了 GHOST_SECURITY_REPO_ID，否则为必需参数）。
• cursor（字符串，可选）：分页游标。
• sort（字符串，可选）：排序字段（created_at、updated_at）。
• order（字符串，可选）：排序顺序（asc、desc）。
• size（数字，可选）：每页大小（1 - 1000）。

📚 详细文档

发布到MCP注册表

此服务器已配置为发布到 MCP注册表。

1. 安装发布者CLI：

brew install mcp-publisher

2. 登录：

mcp-publisher login github

3. 发布：

mcp-publisher publish

server.json 文件包含必要的元数据。在发布到注册表之前，请确保已将软件包发布到NPM。

开发

脚本

• npm run dev：以开发模式运行，支持热重载。
• npm run build：将TypeScript编译为JavaScript。
• npm start：运行已构建的服务器。
• npm run chat：运行CLI聊天机器人。

项目结构

src/
├── index.ts          # 主MCP服务器实现
├── ghost-client.ts   # 幽灵安全API客户端（V2）
├── types.ts          # TypeScript类型定义
└── chatbot.ts        # CLI聊天机器人实现

API参考

此MCP服务器提供了幽灵安全API V2的完整接口。如需详细的API文档，请访问： https://docs.ghostsecurity.ai/api-reference/introduction

📄 许可证

本项目采用MIT许可证。