Ghostwriter MCP

Ghostwriter MCP服务器

A. 模型上下文协议（MCP） 包装服务器 Ghostwriter的 GraphQL API并公开 AI代理（Claude Desktop、VS Code Copilot等）可以调用来管理的工具 客户、项目、报告和渗透测试结果。

______________________________________________________________________

特性

• 搜索和检索客户、项目、报告和结果
• 创建新客户、项目、报告和发现
• 将图书馆的调查结果附在报告中
• 更新报告的发现（复制步骤、受影响实体）
• 生成唯一的项目代号
• 标准 本地MCP客户端的默认传输 上海证券交易所 基于HTTP的客户端的传输

______________________________________________________________________

先决条件

• Python 3.10+
• 运行的Ghostwriter实例，其GraphQL/Hasura API可访问
• Ghostwriter API令牌

______________________________________________________________________

安装

git clone 
cd copilot-try-ghostwriter
python3 -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt

______________________________________________________________________

配置

创建一个 .env 项目根目录中的文件（或导出shell中的变量）：

# Required
GHOSTWRITER_GRAPHQL_URL=https://ghostwriter.example.local/v1/graphql

# Recommended
GHOSTWRITER_API_TOKEN=your_api_token_here

# Optional overrides
GHOSTWRITER_REQUEST_TIMEOUT=10
GHOSTWRITER_DEFAULT_PROJECT_TYPE_ID=1
GHOSTWRITER_DEFAULT_SEVERITY_ID=1
GHOSTWRITER_PAGINATION_LIMIT=50

TLS注释： 默认情况下启用证书验证。如果Ghostwriter使用 自签名证书，将CA添加到系统信任存储中（推荐）。

______________________________________________________________________

运行服务器

stdio--默认值（本地MCP客户端，如Claude Desktop）

python main.py

SSE——HTTP传输（远程或基于HTTP的MCP客户端）

python main.py --transport sse

# Custom host/port
python main.py --transport sse --host 0.0.0.0 --port 8009

所有CLI选项

usage: main.py [-h] [--transport {stdio,sse}] [--host HOST] [--port PORT]

options:
  --transport {stdio,sse}   Transport mode (default: stdio)
  --host HOST               Host to bind for SSE transport (default: 127.0.0.1)
  --port PORT               Port to bind for SSE transport (default: 8009)

______________________________________________________________________

连接到克劳德桌面（stdio）

将以下内容添加到您的 claude_desktop_config.json:

{
  "mcpServers": {
    "ghostwriter": {
      "command": "/absolute/path/to/.venv/bin/python",
      "args": ["/absolute/path/to/copilot-try-ghostwriter/main.py"],
      "env": {
        "GHOSTWRITER_GRAPHQL_URL": "https://ghostwriter.example.local/v1/graphql",
        "GHOSTWRITER_API_TOKEN": "your_token_here"
      }
    }
  }
}

______________________________________________________________________

可用工具

______________________________________________________________________

工作流程

从头开始创建完整的参与度报告时，请遵循以下顺序——每一步 返回下一个所需的ID：

generate_ghostwriter_codename
        ↓
create_ghostwriter_client  → clientId
        ↓
create_ghostwriter_project (clientId) → projectId
        ↓
create_ghostwriter_report  (projectId) → reportId
        ↓
attach_finding_to_report   (reportId) → reportedFindingId
        ↓
update_report_finding      (reportedFindingId)

创建前始终搜索 为了避免重复： 1. search_ghostwriter_clients --再利用 clientId 如果找到 1. search_ghostwriter_projects --再利用 projectId 如果找到 1. search_ghostwriter_reports --再利用 reportId 如果找到

追溯（从已知报告开始）

如果你只有一个 reportId 并且需要回到层次结构：

1. get_ghostwriter_report_by_id → 回报 projectId
2. get_ghostwriter_project_by_id → 回报 clientId
3. get_ghostwriter_client_by_id → 返回完整的客户端详细信息

项目类型ID

环境变量

• GHOSTWRITER_GRAPHQL_URL （或 GHOSTWRITER_URL)：指向Ghostwriter GraphQL端点的URL（例如。 https://ghostwriter.example.local/v1/graphql).必修的。
• GHOSTWRITER_API_TOKEN：用于与Ghostwriter进行身份验证的承载令牌。可选，但推荐。
• GHOSTWRITER_REQUEST_TIMEOUT：请求超时时间（秒）（默认值10）。
• GHOSTWRITER_DEFAULT_PROJECT_TYPE_ID：助手使用的可选默认项目类型id。
• GHOSTWRITER_DEFAULT_SEVERITY_ID：用于创建调查结果的可选默认严重性id。
• GHOSTWRITER_PAGINATION_LIMIT：列表查询的默认分页限制（默认值50）。

注意：默认情况下启用TLS证书验证。如果您在具有自签名证书的主机上运行Ghostwriter，则可以：

• 将CA添加到系统信任存储中（推荐），或
• 在可以禁用证书验证的环境中运行MCP服务器（不建议用于生产）。库有意默认验证证书。

如何跑步

1. 创建virtualenv并安装依赖项（添加 httpx, python-dotenv 等符合要求）：

python3 -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt

1. 填充a .env 提交 GHOSTWRITER_GRAPHQL_URL 和 GHOSTWRITER_API_TOKEN.

1. 启动MCP服务器（示例使用中的FastMCP设置 main.py):

python main.py

代理的上下文

AI绘图工作流程的设计说明和建议

你的目标：让AI代理检查HTTP请求+响应，并自动执行以下操作：

1. 确定请求属于哪个Ghostwriter报告（如果有的话）。
2. 确定哪个库发现（如果有的话）与请求匹配，并最好确定正确的 findingId.
3. 如有必要，使用提供的证据和元数据创建新的发现。
4. 将该发现附加到已确定的报告中（创建reportedFinding行）。
5. 使用复制步骤、受影响的实体和任何其他详细信息更新报告的发现。

建议和改进

• 启发式和证据提取：

- 规范化输入：提取主机名、URL、请求/响应正文、参数、标头和时间戳。 - 对现有发现的标题/描述进行相似性搜索（嵌入+余弦），以找到候选匹配项。 - 如果多个候选对象接近，请将其返回以供人工审核，或应用置信阈值进行自动附加。

• AI代理职责：

- 使用一个小型结构化模式作为代理的输出：{report_hint，finding_int，action，confidence，payload}。 - 操作：附件查找、创建和附件查找、更新报告查找、任务查找。

• 映射策略：

- 首先，按项目ID、报告标题或最近的活动搜索报告——使用时间窗口和主机名来缩小范围。 - 接下来，搜索结果在标题/摘要上进行文本匹配，在提取的证据上进行模糊匹配。 - 如果没有匹配值超过置信阈值，则使用自动生成的标题和包含请求/响应片段的结构化描述创建一个新发现。

• 数据模型建议：

- 存储发现和报告摘要的嵌入，以加快相似性匹配。 - 将最近的报告/项目缓存在内存中，以便更快地缩小候选范围。

• 效率和规模：

- 在可能的情况下批处理API调用（例如，在一个查询中搜索多个结果）。 - 使用分页和限制来避免返回巨大的数据集。 - 如果您希望每分钟发生许多事件，请将繁重的机器学习工作（嵌入、相似性）放在单独的服务或后台作业中。

• 安全与用户体验：

- 仅在信心较高时自动附加；否则，创建一个人类可以批准的建议操作。 - 添加“模拟运行”模式，代理返回计划的更改而不应用它们。