ghostlink

GhostLink

一款经过安全加固的 MCP 服务，让 AI 编码 Agent 能够安全、确定性地访问本地代码仓库。

将其添加到任何支持 STDIO 的 MCP 客户端中。对于 Claude Code，在目标代码仓库根目录中创建 .mcp.json：

{
  "mcpServers": {
    "ghostlink": {
      "command": "npx",
      "args": ["-y", "ghostlink"],
      "env": {
        "GHOSTLINK_REPO_ROOT": "/path/to/target/repo"
      }
    }
  }
}

然后在该目录中运行 claude——即可看到六个代码仓库工具，且所有工具都限制在 GHOSTLINK_REPO_ROOT 范围内。每次工具调用都会返回相同的确定性 ToolEnvelope：

{
  "ok": true,
  "data": { ... },
  "provenance": { "tool": "repo.search", "timestamp": "2026-02-24T...", "duration_ms": 42 }
}

发生错误时，"error": { "code": "...", "message": "..." } 会取代 "data"。完整的工具架构请参阅：docs/TOOLS.md。

工具

工具	描述
repo.search	由 Ripgrep 驱动的正则搜索，支持 glob 筛选、确定性排序和输出上限（最多 200 条结果）
repo.read_file	文件读取，设有大小上限（最多 10MB）、二进制文件检测和截断标记
repo.apply_patch	使用统一差异补丁，支持试运行模式、完整沙箱验证，以及失败时原子回滚
repo.run	执行精选命令（test、lint、typecheck、build、smoke）——不允许任意 shell 命令，仅允许指定参数
git.status	规范化的 Git 状态，包含分支信息、领先/落后跟踪和排序后的文件条目
git.diff	暂存或未暂存差异，支持路径筛选、沙箱验证和输出上限（最多 2MB）

什么是 GhostLink？

GhostLink 是一款本地优先的模型上下文协议服务，通过一组受策略控制的工具向 AI 编码 Agent 提供代码库访问能力。它解决了一个特定问题：AI Agent 需要搜索、读取、修改和验证代码，但授予它们原始 shell 访问权限会带来风险。GhostLink 提供了一个沙箱化的能力层，确保每次工具调用都限制在单一代码仓库根目录内、每个输出都遵循确定性的 JSON 格式，并且每次调用都会记录审计日志。

为什么选择 GhostLink？

能力	含义
安全的本地开发层	代码仓库根目录沙箱、不执行 shell 命令、每次工具调用都生成 JSONL 审计记录
确定性输出	相同输入会生成相同的 JSON 封装格式——支持黄金测试和可预测的 Agent 消费
策略执行	命令允许列表、输出上限、截断标记、超时强制执行——AI 无法造成不受限的损害
Agent 循环基础	专为自主编码 Agent 循环执行的搜索、读取、修改、验证周期而构建
多服务组合	每个代码仓库运行一个 GhostLink 实例，可与同一客户端会话中的其他 MCP 服务组合使用
生产就绪的 Phase 2 基础	架构保留了传输抽象、架构版本控制和身份验证钩子扩展点

架构

GhostLink 采用三层架构，可扩展且无需修改核心代码：

flowchart TD
    T["Transport -- src/index.ts<br/>STDIO now, HTTP/SSE in Phase 2"]
    S["Server factory -- src/server.ts<br/>Transport-agnostic tool registration via MCP SDK + Zod schemas"]
    TL["Tools -- src/core/tools/*<br/>Six tools, each returning ToolEnvelope&lt;T&gt;"]
    P["Policy -- src/core/policy/*<br/>Sandbox enforcement, audit logging, output caps"]
    T --> S --> TL --> P

createServer() 工厂与传输方式无关。在 Phase 2 中添加 HTTP/SSE，只需编写新的传输绑定和身份验证中间件——服务器工厂和所有工具实现都无需更改。Phase 3（Agent 运行时）会将记忆资源和编排作为 GhostLink 的使用方添加，而不是对其进行修改。

快速开始

前置条件

• Node.js 18+
• ripgrep（brew install ripgrep）
• 一个要公开的 Git 代码仓库

安装

通过 npm：

npm install ghostlink

或从源代码安装：

git clone https://github.com/bgorzelic/ghostlink.git
cd ghostlink
npm install
npm run build

冒烟测试（原始 STDIO）

GhostLink 通过 STDIO 使用 JSON-RPC 2.0。直接测试：

echo '{"jsonrpc":"2.0","id":1,"method":"tools/list"}' | \
  GHOSTLINK_REPO_ROOT=/path/to/target/repo node dist/index.js

这会返回全部 6 个工具及其架构。

客户端配置

GhostLink 适用于任何支持 STDIO 传输的 MCP 客户端。本页顶部的 npx 代码片段可在任何地方使用；从源代码检出时，则使用 node 和构建好的入口点：

{
  "ghostlink": {
    "command": "node",
    "args": ["/absolute/path/to/ghostlink/dist/index.js"],
    "env": {
      "GHOSTLINK_REPO_ROOT": "/path/to/target/repo"
    }
  }
}

客户端	配置位置
Claude Code	目标仓库根目录中的 .mcp.json（mcpServers 键），然后在该目录运行 claude
Claude Desktop	~/Library/Application Support/Claude/claude_desktop_config.json（mcpServers 键），然后重启
Cursor、Windsurf、Cline 等	客户端的 MCP 服务配置——请查阅其文档了解文件位置

传输方式始终为 STDIO。可直接使用的 .mcp.json 和 CLAUDE.md 模板位于目标项目的 templates/ 目录中。

安全模型

GhostLink 在每一层都实施纵深防御：

• 仓库根目录沙箱 —— 所有文件操作都限制在 GHOSTLINK_REPO_ROOT 内。在访问任何文件系统之前，都会拒绝路径遍历、符号链接逃逸、空字节以及根目录之外的绝对路径。
• 不执行 Shell 命令 —— repo.run 使用 spawn，并设置 shell: false。命令仅限于固定的允许列表（test、lint、typecheck、build、smoke），且每个命令都有各自的参数允许列表。环境变量会被精简，仅保留 6 个安全变量。
• 输出上限 —— 每个返回大量数据的工具都设有硬性上限（200 条搜索结果、10MB 文件读取、200KB stdout/stderr、2MB 差异）。截断会明确标记，不会悄无声息地发生。
• 原子补丁回滚 —— repo.apply_patch 会在写入任何内容之前验证所有路径并计算所有补丁。如果任何写入失败，已完成的写入会回滚至原始状态。
• 超时强制执行 —— repo.run 会在可配置的超时时间后终止进程（默认 120s，硬性上限 300s），先发送 SIGTERM，再发送 SIGKILL。

完整的威胁模型和缓解措施：docs/SECURITY.md。

审计日志

每次工具调用都会生成一条 JSONL 审计记录：{ts, tool, ok, duration_ms, error_code?, repo_root}。

GHOSTLINK_LOG	行为
stdout（默认）	将 JSONL 审计行写入 stderr
file	将 JSONL 写入 logs/ghostlink.jsonl（达到 10MB 时自动轮换）
off	不记录日志

通过环境变量设置：

GHOSTLINK_LOG=file GHOSTLINK_REPO_ROOT=/path/to/repo node dist/index.js

提示词模板

docs/PROMPTS.md 包含可直接使用的高自主性 Agent 操作提示词，包括编排器提示词、子 Agent 角色定义（协议工程师、工具工程师、安全审查员、测试工程师、文档工程师）以及多实例协调模式。

开发

npm install          # Install dependencies
npm test             # Run test suite (108 tests via Vitest)
npm run lint         # ESLint
npm run typecheck    # TypeScript strict mode check
npm run build        # Compile to dist/
npm run dev          # Dev mode with auto-reload (tsx watch)

编辑后的完整验证：

npm test && npm run lint && npm run typecheck && npm run build

文档

文档	说明
docs/TOOLS.md	权威工具架构（版本化公共 API）
docs/SECURITY.md	威胁模型和缓解措施
docs/QUICKSTART.md	设置、冒烟测试和客户端配置指南
docs/INSPECTOR.md	MCP Inspector 手动测试指南
docs/PROMPTS.md	用于编排和子 Agent 角色的 Agent 提示词
docs/ROADMAP_DETAILED.md	完整产品路线图，包含 Phase 2 和 Phase 3 的交付内容
docs/WHY_GHOSTLINK.md	战略价值主张和架构依据
docs/ENGINEERING_REPORT_v0.1.0.md	v0.1.0 发布报告，包含里程碑历史和决策日志
templates/	可直接用于目标项目的 CLAUDE.md 和 .mcp.json 模板

路线图

Phase 1 —— 本地 STDIO［已发布，v0.1.0］

确定性的工具接口、仓库根目录沙箱、精选命令执行、108 项测试、JSONL 审计日志，npm 包已发布。

阶段 2 —— 远程传输【计划中】

HTTP/SSE 传输、OAuth 2.1 身份验证、多用户租户隔离、按租户限流、架构版本管理，以及带关联 ID 的结构化审计日志。

阶段 3 —— Agent 运行时【未来计划】

通过 MCP 暴露的持久化记忆资源、可选的策略门控记忆写入工具、编排层（位于 GhostLink 之外）、评估循环、子 Agent 协调框架。

许可证

ISC