AI 코딩 에이전트가 로컬 저장소를 검색, 읽기, 패치 및 지정된 명령어를 실행할 수 있도록 샌드박스 및 정책 기반의 접근 권한을 제공합니다.
다른 이름 bgorzelic/ghostlink, @bgorzelic/ghostlink
- 스타
- 0
- Tools
- —
- 다운로드, 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를 열고 mcpServers 아래에 서버를 추가합니다. 위 설치 섹션에 표시된 Cursor 구성을 사용합니다.
Claude Code에서 GhostLink를 어떻게 설정하나요?
대상 저장소 루트에 ghostlink 명령어와 GHOSTLINK_REPO_ROOT 환경 변수를 포함하는 .mcp.json 파일을 생성합니다.
GhostLink로 AI 에이전트에게 파일 접근 권한을 주는 것이 안전한가요?
네, 저장소 루트 기반의 샌드박스를 사용하여 경로 탐색(path traversal) 및 심볼릭 링크 탈출을 차단하며, 허용 목록(allowlist)에 있는 명령어만 사용하도록 제한하여 임의의 셸 실행을 방지합니다.
파일 패치에 실패하면 어떻게 되나요?
쓰기 작업 중 일부라도 실패하면 서버가 원자적 롤백(atomic rollback)을 수행하여 파일을 원래 상태로 되돌립니다.
AI 에이전트가 수행한 작업 로그를 볼 수 있나요?
네, 모든 도구 호출은 stdout 또는 파일로 전송할 수 있는 JSONL 감사 항목을 생성합니다.