Skip to content

LOCAL-MCP-SIDECAR.md

Latest commit

 

History

History
582 lines (466 loc) · 15.8 KB

LOCAL-MCP-SIDECAR.md

File metadata and controls

582 lines (466 loc) · 15.8 KB
Raw

🔌 Local MCP Sidecar

Optional local-mode extension for @omni-skills/server-mcp that adds filesystem-aware tools for client detection, skill management, and MCP config generation around the Awesome Omni Skills catalog.

📊 Status

Feature State
✅ Read-only catalog tools Implemented
✅ Filesystem-aware local tools Implemented
✅ 3 transports (stdio/stream/sse) Implemented
✅ Allowlisted writes Implemented
✅ Preview-before-write defaults Implemented
✅ Client-aware MCP config writing Implemented
✅ HTTP auth + rate limiting Implemented
✅ Release-time signatures and checksums Implemented for generated archives and surfaced by API/MCP
🟡 Local write-time signature enforcement Not enforced yet; local mode previews and writes from the trusted local checkout
🟢 Current client coverage 9 install-capable clients, 16 config-capable clients, 33 config targets, 20 config profiles

🎯 Purpose

Local mode adds filesystem-aware tools on top of the existing read-only MCP catalog surface. Use it when an agent needs to:

  • 🕵️ Detect compatible local AI clients
  • 📋 Inspect installed skills
  • 👁️ Preview skill installation or removal (dry-run)
  • 📦 Apply local skill installation or removal
  • ⚙️ Write a local MCP config file after preview

It deliberately separates two concerns:

  • skill installation targets clients with a stable skills directory that can use install_skills
  • MCP config targets clients or IDEs with a stable documented MCP config format, even if they do not have a skills directory

🔌 Transports

Transport Protocol Use Case
stdio Pipe Direct client integration
stream Streamable HTTP Modern HTTP clients
sse Server-Sent Events Legacy clients

🚀 Enable Local Mode

📦 From repo:

npm run mcp:local
npm run mcp:stream:local
npm run mcp:sse:local

📦 Via CLI:

npm run cli -- mcp stdio --local
npm run cli -- mcp stream --local
npm run cli -- mcp sse --local
npm run cli -- config-mcp --list-targets
npm run cli -- config-mcp --target continue-workspace --transport stream --url http://127.0.0.1:3334/mcp
npm run cli -- config-mcp --target junie-project --transport stream --url http://127.0.0.1:3334/mcp
npm run cli -- config-mcp --target goose-user --transport stream --url http://127.0.0.1:3334/mcp

📦 From published package:

npx awesome-omni-skills mcp stdio --local
npx awesome-omni-skills mcp stream --local
npx awesome-omni-skills mcp sse --local
npx awesome-omni-skills config-mcp --list-targets
npx awesome-omni-skills config-mcp --target junie-project --transport stream --url http://127.0.0.1:3334/mcp
npx awesome-omni-skills config-mcp --target windsurf-user --transport sse --url http://127.0.0.1:3335/sse --write
npx awesome-omni-skills config-mcp --target goose-user --transport stream --url http://127.0.0.1:3334/mcp --write

All commands set OMNI_SKILLS_MCP_MODE=local automatically.

🛠️ Local Tools

When local mode is enabled, these extra tools become available:

Tool Description Default
🕵️ detect_clients Scan for AI clients and their skill/config paths —
📋 list_installed_skills Inspect installed skills for a specific client —
📦 install_skills Install skills into a client's skills directory 🔍 dry-run
🗑️ remove_skills Remove installed skills from a client 🔍 dry-run
⚙️ configure_client_mcp Write MCP config for a specific client 🔍 dry-run

⚠️ install_skills, remove_skills, and configure_client_mcp default to dry-run when dry_run is omitted.

🎯 Supported Targets

📂 Skills Directories

Client Path
🔵 Claude Code ~/.claude/skills
🔵 Cursor ~/.cursor/skills
🟡 Gemini CLI ~/.gemini/skills
🟣 Antigravity ~/.gemini/antigravity/skills
🟢 Kiro ~/.kiro/skills
🔴 Codex CLI ~/.codex/skills or $CODEX_HOME/skills
⚪ OpenCode <workspace>/.opencode/skills
🪿 Goose ~/.agents/skills
🟠 Qwen Code <workspace>/.qwen/skills

These 9 targets are the only first-class install destinations today.

⚙️ MCP Config Files

Target Format
~/.claude/settings.json Claude Code settings JSON
<workspace>/.claude/settings.json Claude project settings JSON
~/.claude.json Legacy Claude JSON (mcpServers)
~/Library/Application Support/Claude/claude_desktop_config.json Claude Desktop JSON (OS-specific)
~/.cursor/mcp.json JSON (mcpServers)
<workspace>/.cursor/mcp.json Cursor workspace JSON (mcpServers)
~/.gemini/settings.json Gemini user JSON (mcpServers)
<workspace>/.gemini/settings.json Gemini project JSON (mcpServers)
~/.gemini/antigravity/mcp.json Antigravity JSON (mcpServers)
~/.kiro/settings/mcp.json Kiro user JSON (mcpServers)
<workspace>/.kiro/settings/mcp.json Kiro project JSON (mcpServers)
~/.codex/config.toml TOML ([mcp_servers])
<workspace>/.mcp.json JSON (mcpServers)
<workspace>/opencode.json OpenCode workspace JSON (mcp)
~/.config/opencode/opencode.json OpenCode user JSON (mcp)
~/.cline/data/settings/cline_mcp_settings.json Cline JSON (mcpServers)
~/.copilot/mcp-config.json GitHub Copilot CLI JSON (mcpServers)
<workspace>/.github/mcp.json GitHub Copilot repository JSON (mcpServers)
~/.config/kilo/kilo.json Kilo CLI user JSON (mcp)
<workspace>/kilo.json Kilo CLI project JSON (mcp)
<workspace>/.kilocode/mcp.json Kilo Code workspace JSON (mcpServers)
<workspace>/.continue/mcpServers/omni-skills.yaml Continue workspace YAML (mcpServers)
<workspace>/.junie/mcp/mcp.json Junie project JSON (mcpServers)
~/.junie/mcp/mcp.json Junie user JSON (mcpServers)
~/.codeium/windsurf/mcp_config.json Windsurf JSON (mcpServers)
~/.config/goose/config.yaml Goose YAML (extensions)
<workspace>/.zed/settings.json Zed workspace JSON (context_servers)
<workspace>/.vscode/mcp.json JSON (servers)
~/.config/Code/User/mcp.json VS Code user JSON (servers)
~/.config/Code - Insiders/User/mcp.json VS Code Insiders user JSON (servers)
<workspace>/.devcontainer/devcontainer.json Nested Dev Container JSON (customizations.vscode.mcp.servers)
Client root mcp.json JSON (per-client format)

That gives the sidecar:

  • 16 config-capable clients or IDEs
  • 33 first-class target paths
  • 20 format profiles

Current first-class config coverage spans:

  • Claude Code and Claude Desktop
  • Cursor
  • VS Code and Dev Containers
  • Gemini CLI
  • Antigravity
  • Kiro
  • Codex CLI
  • Continue
  • Junie
  • Windsurf
  • Goose
  • OpenCode
  • Cline
  • GitHub Copilot CLI
  • Kilo Code
  • Zed

Manual or snippet-only candidates are still intentionally outside the first-class writer set until their public config contracts are stable enough.

🧭 Expansion Policy

Awesome Omni Skills now treats client support as a three-level model:

  1. install-capable A stable skills directory exists, so the CLI and sidecar can install skills directly.
  2. config-capable A stable, documented MCP config format exists, so config-mcp can preview and write a first-class file.
  3. manual or snippet-only The product clearly supports MCP in some form, but the public docs do not justify a safe automatic writer yet.

This is why clients such as JetBrains AI Assistant remain manual/snippet-only, while Roo Code and Postman stay outside the first-class writer set until their safe automatic merge story is strong enough for this project.

🔒 Allowlist Model

The local sidecar only writes under an explicit allowlist.

🟢 Default allowlist:

  • Known client roots under $HOME
  • ~/.codeium for Windsurf user config
  • ~/.copilot for GitHub Copilot CLI
  • ~/.cline for Cline CLI
  • ~/.config/goose for Goose config
  • ~/.config/kilo and ~/.config/opencode for Kilo/OpenCode CLI config
  • $CODEX_HOME (or ~/.codex if unset)
  • Current workspace root
  • <workspace>/.agents
  • <workspace>/.github
  • <workspace>/.kilocode
  • <workspace>/.opencode
  • <workspace>/.zed
  • <workspace>/.continue
  • <workspace>/.vscode

➕ Extend the allowlist:

export OMNI_SKILLS_LOCAL_ALLOWLIST=/absolute/path/one:/absolute/path/two

⚙️ Config Writing Examples

🔵 Claude Code / Project Settings

{
  "mcpServers": {
    "omni-skills": {
      "type": "http",
      "url": "http://127.0.0.1:3334/mcp"
    }
  }
}

🔵 Cursor / Workspace JSON

{
  "mcpServers": {
    "omni-skills": {
      "type": "http",
      "url": "http://127.0.0.1:3334/sse"
    }
  }
}

🟡 Gemini CLI / User Settings

{
  "mcpServers": {
    "omni-skills": {
      "type": "http",
      "url": "http://127.0.0.1:3334/mcp",
      "headers": {
        "Authorization": "Bearer example"
      }
    }
  },
  "mcp": {
    "allowed": ["omni-skills"]
  }
}

🟢 Kiro / User Settings

{
  "mcpServers": {
    "omni-skills": {
      "type": "http",
      "url": "http://127.0.0.1:3334/mcp",
      "disabledTools": ["install_skills"],
      "autoApprove": ["search_skills", "get_skill"]
    }
  }
}

🟣 Antigravity

{
  "mcpServers": {
    "omni-skills": {
      "url": "http://127.0.0.1:3334/mcp"
    }
  }
}

⚪ OpenCode

{
  "mcp": {
    "omni-skills": {
      "type": "local",
      "command": ["/path/to/node", "/path/to/packages/server-mcp/src/server.js"],
      "environment": {
        "OMNI_SKILLS_MCP_MODE": "local"
      },
      "enabled": true
    }
  }
}

🟢 Cline

{
  "mcpServers": {
    "omni-skills": {
      "type": "streamable-http",
      "url": "http://127.0.0.1:3334/mcp"
    }
  }
}

⚫ GitHub Copilot CLI

{
  "mcpServers": {
    "omni-skills": {
      "type": "http",
      "url": "http://127.0.0.1:3334/mcp",
      "tools": ["*"]
    }
  }
}

🔴 Kilo Code

{
  "mcp": {
    "omni-skills": {
      "type": "remote",
      "url": "http://127.0.0.1:3334/mcp",
      "enabled": true
    }
  }
}

🟢 Continue

name: 'Awesome Omni Skills'
version: '<current-package-version>'
schema: 'v1'
mcpServers:
  - name: 'omni-skills'
    transport:
      type: 'streamable-http'
      url: 'http://127.0.0.1:3334/mcp'

🧭 CLI Contract

The sidecar-backed CLI wrapper keeps MCP config generation accessible without direct JSON-RPC calls:

npx awesome-omni-skills config-mcp --list-targets
npx awesome-omni-skills config-mcp --target cline-user --transport stream --url http://127.0.0.1:3334/mcp
npx awesome-omni-skills config-mcp --target copilot-user --transport stream --url http://127.0.0.1:3334/mcp
npx awesome-omni-skills config-mcp --target zed-workspace --transport sse --url http://127.0.0.1:3335/sse
npx awesome-omni-skills config-mcp --target continue-workspace --transport stream --url http://127.0.0.1:3334/mcp
npx awesome-omni-skills config-mcp --target junie-project --transport stream --url http://127.0.0.1:3334/mcp
npx awesome-omni-skills config-mcp --target windsurf-user --transport sse --url http://127.0.0.1:3335/sse --write

Default behavior is preview-only. --write applies the config to the resolved target path under the allowlist.

🌊 Windsurf

{
  "mcpServers": {
    "omni-skills": {
      "serverUrl": "http://127.0.0.1:3334/mcp"
    }
  }
}

⚡ Zed

{
  "context_servers": {
    "omni-skills": {
      "url": "http://127.0.0.1:3334/sse"
    }
  }
}

💜 VS Code

{
  "servers": {
    "omni-skills": {
      "type": "stdio",
      "command": "/path/to/node",
      "args": ["/path/to/packages/server-mcp/src/server.js"],
      "env": {
        "OMNI_SKILLS_MCP_MODE": "local"
      }
    }
  }
}

📦 Dev Container

{
  "customizations": {
    "vscode": {
      "mcp": {
        "servers": {
          "omni-skills": {
            "type": "stdio",
            "command": "/path/to/node",
            "args": ["/path/to/packages/server-mcp/src/server.js"],
            "env": {
              "OMNI_SKILLS_MCP_MODE": "local"
            }
          }
        }
      }
    }
  }
}

🔴 Codex TOML

[mcp_servers.omni-skills]
url = "http://127.0.0.1:3334/mcp"

📋 Generic stdio

{
  "mcpServers": {
    "omni-skills": {
      "command": "/path/to/node",
      "args": ["/path/to/packages/server-mcp/src/server.js"],
      "env": {
        "OMNI_SKILLS_MCP_MODE": "local"
      }
    }
  }
}

🔵 Claude allow/deny lists

The configure_client_mcp tool can also write Claude-specific settings when you pass:

  • allowed_mcp_servers
  • denied_mcp_servers
  • permissions_deny
  • enable_all_project_mcp_servers

💜 VS Code sandboxing

For VS Code and Dev Container targets, configure_client_mcp can also write:

  • sandboxEnabled
  • sandbox.filesystem.allowWrite
  • sandbox.network.allowHosts
  • dev.watch
  • dev.debug.type

This maps to the current VS Code guidance for sandboxing local stdio MCP servers.

🧰 Cross-Client Entry Options

configure_client_mcp now supports richer entry metadata across supported profiles:

  • headers
  • env
  • env_file
  • cwd
  • timeout_ms
  • description
  • include_tools
  • exclude_tools
  • disabled
  • trust

Profile-specific options:

  • Claude: allowed_mcp_servers, denied_mcp_servers, permissions_deny, enable_all_project_mcp_servers
  • Gemini: mcp_allowed_servers, mcp_excluded_servers
  • Kiro: disabled_tools, auto_approve
  • VS Code and Dev Containers: dev_watch, dev_debug_type

📋 Generated Recipes

configure_client_mcp returns recipes alongside the preview or applied config.

These recipes are client-aware guidance blocks, for example:

  • claude mcp add ... --scope user|project
  • gemini mcp add ... --scope user|project
  • codex mcp add ...
  • manual file-edit recipes for Cursor, VS Code, Kiro, and Claude Desktop

The overall strategy is now intentionally conservative:

  • reuse a small set of canonical config families where possible
  • keep bespoke writers only when official docs require a distinct shape
  • avoid inventing automatic writers for undocumented targets

🔐 Hosted HTTP Hardening

The HTTP transports support the same env-driven controls as the catalog API:

Variable Purpose
OMNI_SKILLS_HTTP_BEARER_TOKEN Bearer token auth
OMNI_SKILLS_HTTP_API_KEYS Comma-separated API keys
OMNI_SKILLS_HTTP_ADMIN_TOKEN Admin-only runtime introspection
OMNI_SKILLS_RATE_LIMIT_MAX Max requests per window
OMNI_SKILLS_RATE_LIMIT_WINDOW_MS Rate limit window in ms
OMNI_SKILLS_HTTP_AUDIT_LOG Enable audit logging
OMNI_SKILLS_HTTP_AUDIT_LOG_PATH Write audit log to a file
OMNI_SKILLS_HTTP_ALLOWED_ORIGINS Restrict browser origins
OMNI_SKILLS_HTTP_ALLOWED_IPS Restrict allowed source IPs
OMNI_SKILLS_HTTP_MAINTENANCE_MODE Return 503 for non-admin, non-health routes

🟢 /healthz remains open. /mcp, /sse, and /messages require auth when enabled. /admin/runtime requires the admin token when configured.

🌍 Official Docs That Shape Support Decisions

The current writer set and manual-only boundaries were checked against official product docs, including:

  • Anthropic Claude Code MCP
  • OpenAI Codex CLI and OpenAI Docs MCP
  • Cursor MCP docs
  • Continue MCP docs
  • Kiro MCP docs
  • OpenCode MCP docs
  • Cline MCP docs
  • Kilo Code MCP docs
  • GitHub Copilot CLI docs
  • Zed MCP docs
  • VS Code MCP docs
  • JetBrains AI Assistant MCP docs

Those docs are why some clients receive first-class automatic writers while others remain snippet-only for now.