ClinkX

An MCP server (STDIO) that exposes local tools for CLI delegation and workflow orchestration:

• clink runs a configured CLI adapter — Gemini, Codex, Claude, or anything else you configure — as a subprocess and returns the output.
• context_builder creates a persisted, attachable context bundle from allowed local roots before you delegate to a CLI. It uses deterministic local selection by default and can run explicit curator/finalizer delegate adapters before local validation and materialization.
• list_workflows, resume_workflow, and run_workflow support multi-stage workflow orchestration.

Config-driven. No hardcoded CLI allowlist. PAL-compatible at the field level.

Quick start

Requires Node.js >= 24 and at least one CLI configured as an adapter.

npm install
npm run build
node dist/index.js

stdout carries MCP JSON-RPC frames (one JSON object per line). Logs go to stderr.

Configuration

Adapters are JSON files discovered in this order:

1. CLINKX_CONFIG_PATH (file or directory)
2. ${XDG_CONFIG_HOME:-~/.config}/clinkx/adapters/*.json
3. conf/adapters/*.json (relative to process.cwd())

See docs/configuration.md for the full adapter reference.

Context bundles

Use context_builder when a downstream clink call needs curated repository context without inlining source into the first tool response. The tool requires a bounded anchor: at least one bounded focus_paths entry or nonblank search_terms entry. include_globs can narrow scanning when combined with those anchors, but it does not select context alone. The tool writes a durable run directory with manifest.json and artifacts/bundle.md, then returns one minified JSON receipt.

The receipt includes recommended_clink.absolute_file_paths; pass those paths as the absolute_file_paths field in a later clink call. The handoff is fixed to the persisted artifacts/bundle.md and manifest.json files.

Delegate mode requires an explicit request shape and explicit providers:

{
  "task": "Collect context for the server tool registration",
  "roots": ["/path/to/workspace"],
  "focus_paths": ["src/server.ts"],
  "delegate": {
    "enabled": true,
    "curator": {
      "cli_name": "<curator-cli>",
      "role": "<curator-role>"
    },
    "finalizer": {
      "cli_name": "<finalizer-cli>",
      "role": "<finalizer-role>",
      "min_score": 8.5
    },
    "failure_policy": "fallback",
    "timeout_seconds": 120,
    "max_response_chars": 20000
  }
}

There are no built-in curator or finalizer provider defaults. Provider output is advisory: the server validates strict JSON, reconstructs accepted content from local candidates, reapplies budgets and secret checks, and does not persist raw provider output. failure_policy:"fallback" publishes deterministic local selection as a partial v2 run if delegate curation fails; failure_policy:"fail" returns an error and does not publish a manifest.

Adding an adapter

Create conf/adapters/echo.json:

{
  "name": "echo",
  "command": "node",
  "args": ["-e", "let d='';process.stdin.on('data',c=>d+=c);process.stdin.on('end',()=>process.stdout.write(d));"],
  "parser": "text",
  "prompt_mode": "stdin",
  "timeout_seconds": 60
}

Then start the server with node dist/index.js.

MCP client config

The exact shape depends on the client.

Via npx (recommended):

{
  "mcpServers": {
    "clinkx": {
      "command": "npx",
      "args": ["-y", "clinkx@latest"],
      "env": {
        "CLINKX_ALLOWED_ROOTS": "/path/to/your/workspace"
      }
    }
  }
}

From a local clone:

{
  "mcpServers": {
    "clinkx": {
      "command": "node",
      "args": ["/path/to/clink-mcp/dist/index.js"],
      "env": {
        "CLINKX_ALLOWED_ROOTS": "/path/to/your/workspace"
      }
    }
  }
}

Safety

ClinkX validates what goes into the request: paths, environment variables, and argument policy. It does not sandbox the spawned process.

CLINKX_ALLOWED_ROOTS constrains which file paths the tool accepts. The subprocess runs with the permissions of whoever started ClinkX.

context_builder follows the same input-validation model. It validates roots, blocks symlink escapes, omits high-confidence secrets before writing previews, slices, bundles, or manifests, and persists artifacts for manual retention or cleanup. These artifacts are not a sandbox or an access-control boundary.

See docs/security.md for details.