{
"markdown": "# GhostLink\n\n**A security-hardened MCP server that gives AI coding agents safe, deterministic access to local repositories.**\n\n[](https://github.com/bgorzelic/ghostlink/actions/workflows/ci-typescript.yml)\n[](https://www.npmjs.com/package/@bgorzelic/ghostlink)\n[](tsconfig.json)\n[](.nvmrc)\n[](tests/)\n[](LICENSE)\n\nAdd it to any MCP client that supports STDIO. For Claude Code, create `.mcp.json` in the target repo root:\n\n```json\n{\n \"mcpServers\": {\n \"ghostlink\": {\n \"command\": \"npx\",\n \"args\": [\"-y\", \"@bgorzelic/ghostlink\"],\n \"env\": {\n \"GHOSTLINK_REPO_ROOT\": \"/path/to/target/repo\"\n }\n }\n }\n}\n```\n\nThen run `claude` in that directory — six repo tools appear, all confined to `GHOSTLINK_REPO_ROOT`. Every tool call returns the same deterministic `ToolEnvelope`:\n\n```json\n{\n \"ok\": true,\n \"data\": { ... },\n \"provenance\": { \"tool\": \"repo.search\", \"timestamp\": \"2026-02-24T...\", \"duration_ms\": 42 }\n}\n```\n\nOn error, `\"error\": { \"code\": \"...\", \"message\": \"...\" }` replaces `\"data\"`. Full tool schemas: [docs/TOOLS.md](docs/TOOLS.md).\n\n## Tools\n\n| Tool | Description |\n|---|---|\n| `repo.search` | Ripgrep-powered regex search with glob filtering, deterministic ordering, and output caps (max 200 results) |\n| `repo.read_file` | File read with size caps (max 10MB), binary detection, and truncation flags |\n| `repo.apply_patch` | Unified diff patching with dry-run mode, full sandbox validation, and atomic rollback on failure |\n| `repo.run` | Curated command execution (test, lint, typecheck, build, smoke) -- no arbitrary shell, allowlisted args only |\n| `git.status` | Normalized git status with branch info, ahead/behind tracking, and sorted file entries |\n| `git.diff` | Staged or unstaged diff with path filtering, sandbox validation, and output caps (max 2MB) |\n\n## What is GhostLink?\n\nGhostLink is a local-first [Model Context Protocol](https://modelcontextprotocol.io) 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.\n\n## Why GhostLink?\n\n| Capability | What it means |\n|---|---|\n| Secure local dev plane | Repo-root sandbox, no shell execution, JSONL audit trail on every tool call |\n| Deterministic output | Same input produces the same JSON envelope shape -- enables golden tests and predictable agent consumption |\n| Policy enforcement | Command allowlists, output caps, truncation flags, timeout enforcement -- the AI cannot do unbounded damage |\n| Agent loop foundation | Built for the search, read, patch, verify cycle that autonomous coding agents run in a loop |\n| Multi-server composition | One GhostLink instance per repo, composable with other MCP servers in the same client session |\n| Production-ready Phase 2 base | Transport abstraction, schema versioning, and auth hook seams are preserved in the architecture today |\n\n## Architecture\n\nGhostLink is a three-layer stack designed for extensibility without core changes:\n\n```mermaid\nflowchart TD\n T[\"Transport -- src/index.ts
STDIO now, HTTP/SSE in Phase 2\"]\n S[\"Server factory -- src/server.ts
Transport-agnostic tool registration via MCP SDK + Zod schemas\"]\n TL[\"Tools -- src/core/tools/*
Six tools, each returning ToolEnvelope<T>\"]\n P[\"Policy -- src/core/policy/*
Sandbox enforcement, audit logging, output caps\"]\n T --> S --> TL --> P\n```\n\nThe `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.\n\n## Quick Start\n\n### Prerequisites\n\n- Node.js 18+\n- ripgrep (`brew install ripgrep`)\n- A git repository to expose\n\n### Install\n\nFrom npm:\n\n```bash\nnpm install @bgorzelic/ghostlink\n```\n\nOr from source:\n\n```bash\ngit clone https://github.com/bgorzelic/ghostlink.git\ncd ghostlink\nnpm install\nnpm run build\n```\n\n### Smoke Test (Raw STDIO)\n\nGhostLink speaks JSON-RPC 2.0 over STDIO. Test it directly:\n\n```bash\necho '{\"jsonrpc\":\"2.0\",\"id\":1,\"method\":\"tools/list\"}' | \\\n GHOSTLINK_REPO_ROOT=/path/to/target/repo node dist/index.js\n```\n\nThis returns all 6 tools and their schemas.\n\n## Client Configuration\n\nGhostLink 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:\n\n```json\n{\n \"ghostlink\": {\n \"command\": \"node\",\n \"args\": [\"/absolute/path/to/ghostlink/dist/index.js\"],\n \"env\": {\n \"GHOSTLINK_REPO_ROOT\": \"/path/to/target/repo\"\n }\n }\n}\n```\n\n| Client | Where the config goes |\n|---|---|\n| Claude Code | `.mcp.json` in the target repo root (`mcpServers` key), then run `claude` there |\n| Claude Desktop | `~/Library/Application Support/Claude/claude_desktop_config.json` (`mcpServers` key), then restart |\n| Cursor, Windsurf, Cline, others | Your client's MCP server configuration -- consult its documentation for the file location |\n\nThe transport is always STDIO. Ready-to-use `.mcp.json` and CLAUDE.md templates for target projects live in [templates/](templates/).\n\n## Security Model\n\nGhostLink enforces defense-in-depth at every layer:\n\n- **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.\n- **No shell execution** -- `repo.run` uses `spawn` with `shell: 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.\n- **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.\n- **Atomic patch rollback** -- `repo.apply_patch` validates all paths and computes all patches before writing anything. If any write fails, completed writes are rolled back to their original state.\n- **Timeout enforcement** -- `repo.run` kills processes at configurable timeouts (default 120s, hard cap 300s) with SIGTERM then SIGKILL.\n\nFull threat model and mitigations: [docs/SECURITY.md](docs/SECURITY.md).\n\n## Audit Logging\n\nEvery tool call produces a JSONL audit entry: `{ts, tool, ok, duration_ms, error_code?, repo_root}`.\n\n| `GHOSTLINK_LOG` | Behavior |\n|---|---|\n| `stdout` (default) | JSONL audit lines written to stderr |\n| `file` | JSONL written to `logs/ghostlink.jsonl` (auto-rotates at 10MB) |\n| `off` | No logging |\n\nSet via environment variable:\n\n```bash\nGHOSTLINK_LOG=file GHOSTLINK_REPO_ROOT=/path/to/repo node dist/index.js\n```\n\n## Prompt Templates\n\n[docs/PROMPTS.md](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.\n\n## Development\n\n```bash\nnpm install # Install dependencies\nnpm test # Run test suite (108 tests via Vitest)\nnpm run lint # ESLint\nnpm run typecheck # TypeScript strict mode check\nnpm run build # Compile to dist/\nnpm run dev # Dev mode with auto-reload (tsx watch)\n```\n\nFull verification after edits:\n\n```bash\nnpm test && npm run lint && npm run typecheck && npm run build\n```\n\n## Documentation\n\n| Document | Description |\n|---|---|\n| [docs/TOOLS.md](docs/TOOLS.md) | Canonical tool schemas (versioned public API) |\n| [docs/SECURITY.md](docs/SECURITY.md) | Threat model and mitigations |\n| [docs/QUICKSTART.md](docs/QUICKSTART.md) | Setup, smoke tests, and client configuration walkthrough |\n| [docs/INSPECTOR.md](docs/INSPECTOR.md) | MCP Inspector manual testing guide |\n| [docs/PROMPTS.md](docs/PROMPTS.md) | Agent prompts for orchestration and sub-agent roles |\n| [docs/ROADMAP_DETAILED.md](docs/ROADMAP_DETAILED.md) | Full product roadmap with Phase 2 and Phase 3 deliverables |\n| [docs/WHY_GHOSTLINK.md](docs/WHY_GHOSTLINK.md) | Strategic value proposition and architecture rationale |\n| [docs/ENGINEERING_REPORT_v0.1.0.md](docs/ENGINEERING_REPORT_v0.1.0.md) | v0.1.0 ship report with milestone history and decision log |\n| [templates/](templates/) | Ready-to-use CLAUDE.md and .mcp.json templates for target projects |\n\n## Roadmap\n\n### Phase 1 -- Local STDIO [Shipped, v0.1.0]\n\nDeterministic tool surface, repo-root sandbox, curated command execution, 108 tests, JSONL audit logging, npm package published.\n\n### Phase 2 -- Remote Transport [Planned]\n\nHTTP/SSE transport, OAuth 2.1 authentication, multi-user tenant separation, per-tenant rate limiting, schema versioning, structured audit logging with correlation IDs.\n\n### Phase 3 -- Agent Runtime [Future]\n\nPersistent memory resources exposed via MCP, optional policy-gated memory write tools, orchestration layer (external to GhostLink), evaluation loops, sub-agent coordination framework.\n\n## License\n\nISC\n",
"bytes": 9973,
"sha": "86bbd8a3230da2dcf982f29929c1e8c1b7d3f4b199326045292ee99a9d1ede13",
"repo_slug": "bgorzelic/ghostlink",
"fonte": "repo",
"truncated": false,
"api": "https://agentalog.com/api/listings/mcp_io_github_bgorzelic_ghostlink_3f440cc7/readme"
}