AIコーディングエージェントに対し、ローカルリポジトリへのサンドボックス化されたポリシー制御付きアクセスを提供します。検索、読み取り、パッチ適用、および厳選されたコマンドの実行が可能です。
別名 bgorzelic/ghostlink, @bgorzelic/ghostlink
- スター
- 0
- ツール
- —
- ダウンロード数(30日間)
- —
- 最新バージョン
- 0.1.0
- 最終コミット
- 2026年10月5日
- ライセンス
- ISC
GhostLink MCPとは
AIコーディングエージェントに対し、ローカルリポジトリへのサンドボックス化されたポリシー制御付きアクセスを提供します。検索、読み取り、パッチ適用、および厳選されたコマンドの実行が可能です。
プロジェクトのREADMEから生成された概要
GhostLink MCP server について
GhostLinkは、AIコーディングエージェントがローカルのコードベースとやり取りするための、セキュリティを強化した環境を提供します。これは、Claude Code、Claude Desktop、Cursor、Windsurfなどのクライアントと接続するためにstdioトランスポートを使用する、ローカルファーストのModel Context Protocolサーバーとして機能します。環境変数を通じて特定のリポジトリルートを設定することで、開発者はシステム全体を任意のシェルコマンドにさらすことなく、エージェントに対して検索、読み取り、ファイルの変更といった制御されたアクセス権を付与できます。
このサーバーには、自律的なコーディングサイクル向けに設計された6つの特化型ツールが含まれています。これには、ripgrepを使用した正規表現検索を行うrepo.search、サイズ制限付きで内容を読み取るrepo.read_file、およびアトミックなロールバック機能を備えたコード変更を行うrepo.apply_patchが含まれます。また、test、lint、buildなどの許可された特定のコマンドを実行するrepo.runに加え、バージョン管理タスク用のgit.statusおよびgit.diffも提供します。すべての操作は指定されたディレクトリ内にサンドボックス化されており、エージェントの動作を予測可能にするため、決定論的なJSONエンベロープを返します。
できること
- 1エージェントの操作監査チームは、AIがどのようにコードとやり取りしているかを監視するために、すべてのツール呼び出しのJSONL監査トレイルを保持できます。
プロジェクトの README から作成されています。すべてのユースケースは、その引用と照らし合わせて確認されています。
GhostLink MCPのインストール方法
フォーマット検証日 2026年11月10日Cursor に追加Gooseに追加Claude CodeにGhostLink MCPをインストール
$ claude mcp add --env 'GHOSTLINK_REPO_ROOT=<GHOSTLINK_REPO_ROOT>' ghostlink -- npx -y @bgorzelic/ghostlinkCursorにGhostLink MCPをインストール
~/.cursor/mcp.json
{
"mcpServers": {
"ghostlink": {
"command": "npx",
"args": [
"-y",
"@bgorzelic/ghostlink"
],
"env": {
"GHOSTLINK_REPO_ROOT": "<GHOSTLINK_REPO_ROOT>"
}
}
}
}VS CodeにGhostLink MCPをインストール
.vscode/mcp.json
{
"servers": {
"ghostlink": {
"type": "stdio",
"command": "npx",
"args": [
"-y",
"@bgorzelic/ghostlink"
],
"env": {
"GHOSTLINK_REPO_ROOT": "<GHOSTLINK_REPO_ROOT>"
}
}
}
}VS Code CLIにGhostLink MCPをインストール
$ code --add-mcp '{"name":"ghostlink","type":"stdio","command":"npx","args":["-y","@bgorzelic/ghostlink"],"env":{"GHOSTLINK_REPO_ROOT":"<GHOSTLINK_REPO_ROOT>"}}'Claude DesktopにGhostLink MCPをインストール
claude_desktop_config.json
{
"mcpServers": {
"ghostlink": {
"command": "npx",
"args": [
"-y",
"@bgorzelic/ghostlink"
],
"env": {
"GHOSTLINK_REPO_ROOT": "<GHOSTLINK_REPO_ROOT>"
}
}
}
}CodexにGhostLink MCPをインストール
$ codex mcp add ghostlink --env 'GHOSTLINK_REPO_ROOT=<GHOSTLINK_REPO_ROOT>' -- npx -y @bgorzelic/ghostlinkCodex config.tomlにGhostLink MCPをインストール
~/.codex/config.toml
[mcp_servers.ghostlink] command = "npx" args = ["-y", "@bgorzelic/ghostlink"] [mcp_servers.ghostlink.env] GHOSTLINK_REPO_ROOT = "<GHOSTLINK_REPO_ROOT>"
Gemini CLIにGhostLink MCPをインストール
$ gemini mcp add -s user -e 'GHOSTLINK_REPO_ROOT=<GHOSTLINK_REPO_ROOT>' ghostlink npx -- -y @bgorzelic/ghostlinkGemini settings.jsonにGhostLink MCPをインストール
~/.gemini/settings.json
{
"mcpServers": {
"ghostlink": {
"command": "npx",
"args": [
"-y",
"@bgorzelic/ghostlink"
],
"env": {
"GHOSTLINK_REPO_ROOT": "<GHOSTLINK_REPO_ROOT>"
}
}
}
}設定
GHOSTLINK_REPO_ROOT必須Absolute path to the repository the server is confined to. Every tool call is sandboxed beneath this path.
GHOSTLINK_LOGOptional path for the JSON audit log of tool calls. Omit to disable file logging.
| 名前 | 説明 | 種類 |
|---|---|---|
| GHOSTLINK_REPO_ROOT | Absolute path to the repository the server is confined to. Every tool call is sandboxed beneath this path. | 必須 |
| GHOSTLINK_LOG | Optional path for the JSON audit log of tool calls. Omit to disable file logging. |
自動チェック
実行日 2026年11月14日完全なレポート →自動チェックに合格しました。これはセキュリティ監査ではありません。コードを読み、サーバーに必要最小限のアクセス権を与えてください。 チェックの仕組み
- ソースリポジトリがリンクされており、アクセス可能bgorzelic/ghostlink is public and reachablegithub.com/bgorzelic/ghostlink ↗合格
- パッケージがこのリポジトリをソースとして指定未チェック
- ビルドの来歴 (Sigstore 証明)未チェック
- オープンソースライセンス (OSI)ISCspdx.org/licenses/ISC.html ↗合格
- 過去1年以内にコミットまたはリリースありLast commit or release 2026-10-05github.com/bgorzelic/ghostlink ↗合格
- OpenSSF Scorecard未チェック
- パッケージ名が有名なパッケージに酷似していないNo popular package one edit away from @bgorzelic/ghostlink合格
- パッケージおよびその依存関係に重大な勧告なしthe package checked; no critical advisoryosv.dev ↗合格
- モデルへの隠れた指示がない0 tool descriptions and the README read; no override phrases, credential paths or hidden characters合格
- 破壊的なツールがラベル付けされている未チェック
- リモートエンドポイントが MCP ハンドシェイクに応答未チェック
README
GitHubで見るGhostLink
A security-hardened MCP server that gives AI coding agents safe, deterministic access to local repositories.
Add it to any MCP client that supports STDIO. For Claude Code, create .mcp.json in the target repo root:
{
"mcpServers": {
"ghostlink": {
"command": "npx",
"args": ["-y", "ghostlink"],
"env": {
"GHOSTLINK_REPO_ROOT": "/path/to/target/repo"
}
}
}
}
Then run claude in that directory — six repo tools appear, all confined to GHOSTLINK_REPO_ROOT. Every tool call returns the same deterministic ToolEnvelope:
{
"ok": true,
"data": { ... },
"provenance": { "tool": "repo.search", "timestamp": "2026-02-24T...", "duration_ms": 42 }
}
On error, "error": { "code": "...", "message": "..." } replaces "data". Full tool schemas: docs/TOOLS.md.
Tools
| Tool | Description |
|---|---|
repo.search |
Ripgrep-powered regex search with glob filtering, deterministic ordering, and output caps (max 200 results) |
repo.read_file |
File read with size caps (max 10MB), binary detection, and truncation flags |
repo.apply_patch |
Unified diff patching with dry-run mode, full sandbox validation, and atomic rollback on failure |
repo.run |
Curated command execution (test, lint, typecheck, build, smoke) -- no arbitrary shell, allowlisted args only |
git.status |
Normalized git status with branch info, ahead/behind tracking, and sorted file entries |
git.diff |
Staged or unstaged diff with path filtering, sandbox validation, and output caps (max 2MB) |
What is GhostLink?
GhostLink is a local-first Model Context Protocol server that exposes your codebase to AI coding agents through a small set of policy-gated tools. It solves a specific problem: AI agents need to search, read, patch, and verify code, but giving them raw shell access is a liability. GhostLink provides a sandboxed capability plane where every tool call is confined to a single repository root, every output follows a deterministic JSON shape, and every invocation is audit-logged.
Why GhostLink?
| Capability | What it means |
|---|---|
| Secure local dev plane | Repo-root sandbox, no shell execution, JSONL audit trail on every tool call |
| Deterministic output | Same input produces the same JSON envelope shape -- enables golden tests and predictable agent consumption |
| Policy enforcement | Command allowlists, output caps, truncation flags, timeout enforcement -- the AI cannot do unbounded damage |
| Agent loop foundation | Built for the search, read, patch, verify cycle that autonomous coding agents run in a loop |
| Multi-server composition | One GhostLink instance per repo, composable with other MCP servers in the same client session |
| Production-ready Phase 2 base | Transport abstraction, schema versioning, and auth hook seams are preserved in the architecture today |
Architecture
GhostLink is a three-layer stack designed for extensibility without core changes:
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<T>"]
P["Policy -- src/core/policy/*<br/>Sandbox enforcement, audit logging, output caps"]
T --> S --> TL --> P
The createServer() factory knows nothing about transport. Adding HTTP/SSE in Phase 2 means writing a new transport binding and auth middleware -- the server factory and all tool implementations remain unchanged. Phase 3 (agent runtime) adds memory resources and orchestration as consumers of GhostLink, not modifications to it.
Quick Start
Prerequisites
- Node.js 18+
- ripgrep (
brew install ripgrep) - A git repository to expose
Install
From npm:
npm install ghostlink
Or from source:
git clone https://github.com/bgorzelic/ghostlink.git
cd ghostlink
npm install
npm run build
Smoke Test (Raw STDIO)
GhostLink speaks JSON-RPC 2.0 over STDIO. Test it directly:
echo '{"jsonrpc":"2.0","id":1,"method":"tools/list"}' | \
GHOSTLINK_REPO_ROOT=/path/to/target/repo node dist/index.js
This returns all 6 tools and their schemas.
Client Configuration
GhostLink works with any MCP client that supports STDIO transport. The npx snippet at the top of this page works everywhere; a source checkout uses node with the built entry point instead:
{
"ghostlink": {
"command": "node",
"args": ["/absolute/path/to/ghostlink/dist/index.js"],
"env": {
"GHOSTLINK_REPO_ROOT": "/path/to/target/repo"
}
}
}
| Client | Where the config goes |
|---|---|
| Claude Code | .mcp.json in the target repo root (mcpServers key), then run claude there |
| Claude Desktop | ~/Library/Application Support/Claude/claude_desktop_config.json (mcpServers key), then restart |
| Cursor, Windsurf, Cline, others | Your client's MCP server configuration -- consult its documentation for the file location |
The transport is always STDIO. Ready-to-use .mcp.json and CLAUDE.md templates for target projects live in templates/.
Security Model
GhostLink enforces defense-in-depth at every layer:
- Repo-root sandbox -- All file operations confined to
GHOSTLINK_REPO_ROOT. Path traversal, symlink escape, null bytes, and absolute paths outside the root are all rejected before any filesystem access. - No shell execution --
repo.runusesspawnwithshell: false. Commands are limited to a fixed allowlist (test, lint, typecheck, build, smoke) with per-command argument allowlists. Environment is stripped to six safe variables. - Output caps -- Every tool that returns bulk data enforces hard maximums (200 search results, 10MB file reads, 200KB stdout/stderr, 2MB diffs). Truncation is flagged, never silent.
- Atomic patch rollback --
repo.apply_patchvalidates all paths and computes all patches before writing anything. If any write fails, completed writes are rolled back to their original state. - Timeout enforcement --
repo.runkills processes at configurable timeouts (default 120s, hard cap 300s) with SIGTERM then SIGKILL.
Full threat model and mitigations: docs/SECURITY.md.
Audit Logging
Every tool call produces a JSONL audit entry: {ts, tool, ok, duration_ms, error_code?, repo_root}.
GHOSTLINK_LOG |
Behavior |
|---|---|
stdout (default) |
JSONL audit lines written to stderr |
file |
JSONL written to logs/ghostlink.jsonl (auto-rotates at 10MB) |
off |
No logging |
Set via environment variable:
GHOSTLINK_LOG=file GHOSTLINK_REPO_ROOT=/path/to/repo node dist/index.js
Prompt Templates
docs/PROMPTS.md contains ready-to-use prompts for high-autonomy agent operation, including orchestrator prompts, sub-agent role definitions (Protocol Engineer, Toolsmith, Security Reviewer, Test Engineer, Docs Engineer), and multi-instance coordination patterns.
Development
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)
Full verification after edits:
npm test && npm run lint && npm run typecheck && npm run build
Documentation
| Document | Description |
|---|---|
| docs/TOOLS.md | Canonical tool schemas (versioned public API) |
| docs/SECURITY.md | Threat model and mitigations |
| docs/QUICKSTART.md | Setup, smoke tests, and client configuration walkthrough |
| docs/INSPECTOR.md | MCP Inspector manual testing guide |
| docs/PROMPTS.md | Agent prompts for orchestration and sub-agent roles |
| docs/ROADMAP_DETAILED.md | Full product roadmap with Phase 2 and Phase 3 deliverables |
| docs/WHY_GHOSTLINK.md | Strategic value proposition and architecture rationale |
| docs/ENGINEERING_REPORT_v0.1.0.md | v0.1.0 ship report with milestone history and decision log |
| templates/ | Ready-to-use CLAUDE.md and .mcp.json templates for target projects |
Roadmap
Phase 1 -- Local STDIO [Shipped, v0.1.0]
Deterministic tool surface, repo-root sandbox, curated command execution, 108 tests, JSONL audit logging, npm package published.
Phase 2 -- Remote Transport [Planned]
HTTP/SSE transport, OAuth 2.1 authentication, multi-user tenant separation, per-tenant rate limiting, schema versioning, structured audit logging with correlation IDs.
Phase 3 -- Agent Runtime [Future]
Persistent memory resources exposed via MCP, optional policy-gated memory write tools, orchestration layer (external to GhostLink), evaluation loops, sub-agent coordination framework.
License
ISC
GhostLink MCPのよくある質問
GhostLink MCPをClaude Codeに追加するには
ターミナルでclaude mcp add --env 'GHOSTLINK_REPO_ROOT=<GHOSTLINK_REPO_ROOT>' ghostlink -- npx -y @bgorzelic/ghostlinkを実行します。すべてのプロジェクトで利用するには--scope userを追加します。
GhostLink MCPをCursorに追加するには
~/.cursor/mcp.jsonを開き、上記のインストールセクションに示すCursor設定を使ってmcpServersの下にサーバーを追加します。
Claude CodeでGhostLinkを設定するにはどうすればよいですか?
対象リポジトリのルートに、ghostlinkコマンドとGHOSTLINK_REPO_ROOT環境変数を含む.mcp.jsonファイルを作成してください。
GhostLinkでAIエージェントにファイルへのアクセス権を与えるのは安全ですか?
はい。リポジトリルートのサンドボックスを使用しており、パス・トラバーサルやシンボリックリンクによる脱出を拒否します。また、コマンドの許可リストを使用することで、任意のシェル実行を防止します。
ファイルパッチの適用に失敗した場合はどうなりますか?
書き込み操作のいずれかの部分で失敗した場合、サーバーはアトミックなロールバックを実行し、ファイルを元の状態に戻します。
AIエージェントが行った操作のログを確認できますか?
はい。すべてのツール呼び出しはJSONL形式の監査エントリを生成し、stdoutまたはファイルに出力できます。