@agimon-ai/mcp-proxy 0.4.0

package/LICENSE

@@ -0,0 +1,52 @@
+Business Source License 1.1
+
+Parameters
+
+Licensor:             AgiFlow
+Licensed Work:        @agimon-ai/public-packages
+                      The Licensed Work is (c) 2026 AgiFlow.
+Additional Use Grant: None
+Change Date:          2030-03-06
+Change License:       Apache License, Version 2.0
+
+Terms
+
+The Licensor hereby grants you the right to copy, modify, create derivative
+works, redistribute, and make non-production use of the Licensed Work. The
+Licensor may make an Additional Use Grant, above, permitting limited
+production use.
+
+Effective on the Change Date, or the fourth anniversary of the first publicly
+available distribution of a specific version of the Licensed Work under this
+License, whichever comes first, the Licensor hereby grants you rights under
+the terms of the Change License, and the rights granted in the paragraph
+above terminate.
+
+If your use of the Licensed Work does not comply with the requirements
+currently in effect as described in this License, you must purchase a
+commercial license from the Licensor, its affiliated entities, or authorized
+resellers, or you must refrain from using the Licensed Work.
+
+All copies of the original and modified Licensed Work, and derivative works
+of the Licensed Work, are subject to this License. This License applies
+separately for each version of the Licensed Work and the Change Date may vary
+for each version of the Licensed Work released by Licensor.
+
+You must conspicuously display this License on each original or modified copy
+of the Licensed Work. If you receive the Licensed Work in original or
+modified form from a third party, the terms and conditions set forth in this
+License apply to your use of that work.
+
+Any use of the Licensed Work in violation of this License will automatically
+terminate your rights under this License for the current and all other
+versions of the Licensed Work.
+
+This License does not grant you any right in any trademark or logo of
+Licensor or its affiliates (provided that you may use a trademark or logo of
+Licensor as expressly required by this License).
+
+TO THE EXTENT PERMITTED BY APPLICABLE LAW, THE LICENSED WORK IS PROVIDED ON
+AN "AS IS" BASIS. LICENSOR HEREBY DISCLAIMS ALL WARRANTIES AND CONDITIONS,
+EXPRESS OR IMPLIED, INCLUDING (WITHOUT LIMITATION) WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, NON-INFRINGEMENT, AND
+TITLE.

package/README.md

@@ -0,0 +1,530 @@
+# @agimon-ai/mcp-proxy
+
+MCP proxy for aggregating multiple MCP servers behind one endpoint.
+
+`mcp-proxy` supports three proxy modes:
+
+- `meta`: expose `describe_tools` and `use_tool`
+- `flat`: expose proxied tools and resources directly
+- `search`: expose `describe_tools`, `list_tools`, and `use_tool`
+
+Use this when:
+- you want one MCP entry instead of many
+- you want cached startup metadata across multiple downstream servers
+- you want to choose between meta-tool routing and direct flat exposure
+
+## Quick Start
+
+### 1. Create Configuration
+
+```bash
+npx @agimon-ai/mcp-proxy init
+```
+
+This creates `mcp-config.yaml`:
+
+```yaml
+mcpServers:
+  filesystem:
+    command: npx
+    args:
+      - -y
+      - "@modelcontextprotocol/server-filesystem"
+      - "${HOME}/Documents"
+    config:
+      instruction: "Access files in the Documents folder"
+
+  scaffold-mcp:
+    command: npx
+    args:
+      - -y
+      - "@agimon-ai/scaffold-mcp"
+      - "mcp-serve"
+    config:
+      instruction: "Scaffold projects and features"
+```
+
+### 2. Configure Your Agent
+
+Add to your MCP config (`.mcp.json`, `.cursor/mcp.json`, etc.):
+
+```json
+{
+  "mcpServers": {
+    "mcp-proxy": {
+      "command": "npx",
+      "args": ["-y", "@agimon-ai/mcp-proxy", "mcp-serve", "--config", "./mcp-config.yaml"]
+    }
+  }
+}
+```
+
+To change proxy behavior, set `--proxy-mode`:
+
+```json
+{
+  "mcpServers": {
+    "mcp-proxy": {
+      "command": "npx",
+      "args": ["-y", "@agimon-ai/mcp-proxy", "mcp-serve", "--proxy-mode", "search", "--config", "./mcp-config.yaml"]
+    }
+  }
+}
+```
+
+### 3. Start Using
+
+`mcp-proxy` now fronts the configured downstream servers through one MCP server.
+
+---
+
+## Configuration
+
+### Proxy Modes
+
+Use `mcp-serve --proxy-mode <mode>` to control how mcp-proxy exposes downstream tools.
+
+`meta` mode:
+- Default mode
+- Exposes `describe_tools` and `use_tool`
+- `describe_tools` includes the proxied capability catalog in its description
+
+`flat` mode:
+- Exposes proxied tools directly in `tools/list`
+- Exposes proxied resources directly in `resources/list`
+- Name clashes are prefixed as `serverName__toolName` or `serverName__resourceUri`
+- `describe_tools` is still exposed when file-based skills or prompt-based skills exist
+
+`search` mode:
+- Exposes `describe_tools`, `list_tools`, and `use_tool`
+- `describe_tools` stays compact and is used for schemas and skill instructions
+- `list_tools` shows server capability summaries and can filter results by capability or server
+
+### Server Types
+
+```yaml
+mcpServers:
+  # Stdio server (local command)
+  local-server:
+    command: npx
+    args:
+      - -y
+      - "@modelcontextprotocol/server-example"
+    env:
+      API_KEY: "${MY_API_KEY}"
+    config:
+      instruction: "Description for the AI agent"
+
+  # HTTP/SSE server (remote)
+  remote-server:
+    url: https://api.example.com/mcp
+    type: sse  # or http
+    headers:
+      Authorization: "Bearer ${TOKEN}"
+    config:
+      instruction: "Remote server description"
+
+  # Disabled server (skipped)
+  disabled-server:
+    command: node
+    args: ["server.js"]
+    disabled: true
+
+  # Custom timeout for slow servers
+  slow-server:
+    command: npx
+    args: ["-y", "@heavy/mcp-package"]
+    timeout: 60000  # 60 seconds (default: 30000)
+```
+
+### Environment Variables
+
+Use `${VAR_NAME}` syntax:
+
+```yaml
+mcpServers:
+  api-server:
+    command: npx
+    args:
+      - "@mycompany/mcp-server"
+      - "${HOME}/data"           # Expands to /Users/username/data
+    env:
+      API_KEY: "${MY_API_KEY}"   # Reads from environment
+```
+
+### Tool Blacklisting
+
+Prevent specific downstream tools from being listed or executed:
+
+```yaml
+mcpServers:
+  filesystem:
+    command: npx
+    args: ["-y", "@modelcontextprotocol/server-filesystem", "/workspace"]
+    config:
+      instruction: "File system access (read-only)"
+      toolBlacklist:
+        - write_file
+        - create_directory
+        - delete_file
+```
+
+Blacklisted tools:
+- Won't appear in tool listings
+- Return an error if called
+
+### Compact Tool Descriptions
+
+Omit downstream tool descriptions from capability listings:
+
+```yaml
+mcpServers:
+  filesystem:
+    command: npx
+    args: ["-y", "@modelcontextprotocol/server-filesystem", "/workspace"]
+    config:
+      omitToolDescription: true  # Show only tool names
+```
+
+**Default output:**
+```
+filesystem:
+  - read_file: Read contents of a file at the specified path...
+  - list_directory: List all files and directories...
+```
+
+**With omitToolDescription:**
+```
+filesystem:
+  read_file, list_directory, search_files
+```
+
+### Skills
+
+File-based skills are loaded from `SKILL.md` files and exposed through `describe_tools`.
+
+#### Configuration
+
+Enable file-based skills by adding a `skills` section:
+
+```yaml
+mcpServers:
+  # ... your MCP servers
+
+skills:
+  paths:
+    - ".claude/skills"           # Relative to config file
+    - "/absolute/path/to/skills" # Absolute paths also supported
+```
+
+#### Skill File Structure
+
+Example:
+```
+.claude/skills/
+├── pdf/
+│   └── SKILL.md
+└── data-analysis/
+    └── SKILL.md
+```
+
+`SKILL.md` format:
+```markdown
+---
+name: pdf
+description: Create and manipulate PDF documents
+---
+
+# PDF Skill
+
+This skill helps you work with PDF files...
+
+## Usage
+...
+```
+
+#### Required Frontmatter
+
+Each `SKILL.md` must define:
+- `name`: Unique identifier for the skill
+- `description`: Brief description shown to clients
+
+#### Precedence
+
+When multiple paths are configured, skills from earlier paths take precedence over skills with the same name from later paths.
+
+### Prompt-Based Skills
+
+You can also expose MCP prompts as skills.
+
+#### Auto-Detection From Frontmatter
+
+If prompt content contains YAML frontmatter with `name` and `description`, `mcp-proxy` can expose it as a skill.
+
+Prompt content example:
+```markdown
+---
+name: code-reviewer
+description: Review code for best practices and potential issues
+---
+
+# Code Review Instructions
+
+When reviewing code, follow these guidelines...
+```
+
+Some servers, such as `@agimon-ai/scaffold-mcp`, support `--prompt-as-skill` and can emit that frontmatter automatically:
+
+```yaml
+mcpServers:
+  scaffold-mcp:
+    command: npx
+    args:
+      - -y
+      - "@agimon-ai/scaffold-mcp"
+      - "mcp-serve"
+      - "--prompt-as-skill"  # Enables front-matter in prompts
+```
+
+Multi-line descriptions are supported:
+
+```markdown
+---
+name: complex-skill
+description: |
+  A skill that does multiple things:
+  - First capability
+  - Second capability
+  - Third capability
+---
+```
+
+#### Explicit Configuration
+
+You can also configure prompt-to-skill mappings explicitly:
+
+```yaml
+mcpServers:
+  my-server:
+    command: npx
+    args:
+      - -y
+      - "@mycompany/mcp-server"
+    config:
+      instruction: "My MCP server"
+      prompts:
+        code-review:
+          skill:
+            name: code-reviewer
+            description: "Review code for best practices and potential issues"
+            folder: "./prompts/code-review"  # Optional: resource folder
+        documentation:
+          skill:
+            name: doc-generator
+            description: "Generate documentation from code"
+```
+
+#### Skill Configuration Fields (Explicit Config)
+
+| Field | Required | Description |
+|-------|----------|-------------|
+| `name` | Yes | Unique skill identifier shown to clients |
+| `description` | Yes | Brief description of what the skill does |
+| `folder` | No | Optional folder path for skill resources |
+
+#### Skill Naming and Precedence
+
+- **File-based skills** take precedence over prompt-based skills with the same name
+- Skills are only prefixed with `skill__` when they clash with MCP tool names
+- Skills that only clash with other skills are deduplicated (first one wins, no prefix)
+
+## MCP Tools
+
+The MCP tools exposed by `mcp-proxy` depend on `--proxy-mode`.
+
+### `describe_tools`
+
+Returns detailed tool schemas and skill instructions.
+
+```json
+{
+  "toolNames": ["read_file", "write_file"]
+}
+```
+
+### `use_tool`
+
+Executes a proxied tool in `meta` and `search` modes.
+
+```json
+{
+  "toolName": "read_file",
+  "toolArgs": {
+    "path": "/path/to/file"
+  }
+}
+```
+
+### `list_tools`
+
+Only available in `search` mode. Returns tool names grouped by proxied server, with server capability summaries and optional filtering.
+
+```json
+{
+  "capability": "review",
+  "serverName": "architect-mcp"
+}
+```
+
+---
+
+## CLI Commands
+
+```bash
+# Start MCP server (stdio, for Claude Code/Cursor)
+npx @agimon-ai/mcp-proxy mcp-serve --config ./mcp-config.yaml
+
+# Start and clear the cached definitions first
+npx @agimon-ai/mcp-proxy mcp-serve --config ./mcp-config.yaml --clear-definitions-cache
+
+# Start with HTTP transport
+npx @agimon-ai/mcp-proxy mcp-serve --config ./mcp-config.yaml --type http --port 3000
+
+# Start stdio-http bridge (reuses existing HTTP server on host/port when available)
+npx @agimon-ai/mcp-proxy mcp-serve --config ./mcp-config.yaml --type stdio-http --host 127.0.0.1 --port 3000
+
+# Start stdio-http bridge with explicit search proxy mode
+npx @agimon-ai/mcp-proxy mcp-serve --config ./mcp-config.yaml --type stdio-http --proxy-mode search --host 127.0.0.1 --port 3000
+
+# Initialize config file
+npx @agimon-ai/mcp-proxy init --output mcp-config.yaml
+
+# Pre-download packages for faster startup
+npx @agimon-ai/mcp-proxy prefetch --config ./mcp-config.yaml
+
+# Pre-download packages and build a definitions cache for faster discovery
+npx @agimon-ai/mcp-proxy prefetch --config ./mcp-config.yaml --definitions-out ./.cache/mcp-proxy-definitions.json
+
+# Search tools across configured servers
+npx @agimon-ai/mcp-proxy search-tools --config ./mcp-config.yaml
+
+# Search tools as JSON
+npx @agimon-ai/mcp-proxy search-tools --config ./mcp-config.yaml --json
+
+# Filter tools by capability or server
+npx @agimon-ai/mcp-proxy search-tools --config ./mcp-config.yaml --capability review
+npx @agimon-ai/mcp-proxy search-tools --config ./mcp-config.yaml --server filesystem
+
+# Get tool details
+npx @agimon-ai/mcp-proxy describe-tools --config ./mcp-config.yaml --tools read_file,write_file
+
+# Execute a tool directly
+npx @agimon-ai/mcp-proxy use-tool --config ./mcp-config.yaml --tool-name read_file --args '{"path": "/tmp/test.txt"}'
+
+# List all resources from configured servers
+npx @agimon-ai/mcp-proxy list-resources --config ./mcp-config.yaml
+
+# Filter resources by server
+npx @agimon-ai/mcp-proxy list-resources --config ./mcp-config.yaml --server my-server
+
+# Read a resource by URI
+npx @agimon-ai/mcp-proxy read-resource --config ./mcp-config.yaml file:///readme.md
+
+# Read from a specific server
+npx @agimon-ai/mcp-proxy read-resource --config ./mcp-config.yaml --server my-server file:///readme.md
+
+# List prompts from configured servers
+npx @agimon-ai/mcp-proxy list-prompts --config ./mcp-config.yaml
+
+# Get a prompt by name
+npx @agimon-ai/mcp-proxy get-prompt --config ./mcp-config.yaml scaffold-feature
+
+# Get a prompt from a specific server with arguments
+npx @agimon-ai/mcp-proxy get-prompt --config ./mcp-config.yaml --server scaffold-mcp --args '{"projectPath":"apps/web"}' scaffold-feature
+```
+
+### Prefetch Command
+
+Pre-download packages used by MCP servers (npx, pnpx, uvx, uv) and optionally build a cached definitions file for faster tool/prompt discovery during `mcp-serve` startup:
+
+```bash
+# Prefetch all packages
+npx @agimon-ai/mcp-proxy prefetch --config ./mcp-config.yaml
+
+# Prefetch packages and write a definitions cache
+npx @agimon-ai/mcp-proxy prefetch --config ./mcp-config.yaml --definitions-out ./.cache/mcp-proxy-definitions.json
+
+# Build only the definitions cache
+npx @agimon-ai/mcp-proxy prefetch --config ./mcp-config.yaml --definitions-out ./.cache/mcp-proxy-definitions.yaml --skip-packages
+
+# Clear the default definitions cache
+npx @agimon-ai/mcp-proxy prefetch --config ./mcp-config.yaml --clear-definitions-cache --skip-packages
+
+# Dry run - see what would be prefetched
+npx @agimon-ai/mcp-proxy prefetch --config ./mcp-config.yaml --dry-run
+
+# Run prefetch in parallel (faster)
+npx @agimon-ai/mcp-proxy prefetch --config ./mcp-config.yaml --parallel
+
+# Filter by package manager
+npx @agimon-ai/mcp-proxy prefetch --config ./mcp-config.yaml --filter npx
+```
+
+| Option | Description |
+|--------|-------------|
+| `-c, --config` | Path to config file |
+| `-p, --parallel` | Run prefetch commands in parallel |
+| `-d, --dry-run` | Show what would be prefetched without executing |
+| `-f, --filter` | Filter by package manager: `npx`, `pnpx`, `uvx`, or `uv` |
+| `--definitions-out` | Write a JSON or YAML definitions cache file for `mcp-serve` |
+| `--skip-packages` | Skip package prefetch and only write the definitions cache |
+| `--clear-definitions-cache` | Delete the effective definitions cache file before continuing |
+
+### Definitions Cache Workflow
+
+For installations with many MCP servers, especially stdio-backed servers, `mcp-serve` now tries to use a definitions cache automatically. The default cache path is under `~/.aicode-toolkit/`, and the filename is derived from the sanitized absolute config path. For example, `/tmp/project/mcp-config.yaml` becomes `~/.aicode-toolkit/tmp_project_mcp-config.yaml.definitions-cache.json`.
+
+If that cache file exists and matches the current config, `mcp-proxy` starts from cached tool/prompt metadata and connects to downstream MCP servers on demand. If the cache is missing or stale, `mcp-proxy` keeps the current eager startup behavior and writes a fresh cache in the background for the next run.
+
+You can still prebuild the cache explicitly:
+
+```bash
+# Step 1: Warm packages and cache definitions
+npx @agimon-ai/mcp-proxy prefetch --config ./mcp-config.yaml --definitions-out ./.cache/mcp-proxy-definitions.json
+
+# Step 2: Start mcp-proxy using the prefetched definitions
+npx @agimon-ai/mcp-proxy mcp-serve --config ./mcp-config.yaml --definitions-cache ./.cache/mcp-proxy-definitions.json
+```
+
+The definitions cache stores tool schemas, prompt metadata, and prompt-based skill metadata. Use `--clear-definitions-cache` on `mcp-serve` or `prefetch` to delete the cache and force a cold start.
+
+### Server Options
+
+| Option | Description | Default |
+|--------|-------------|---------|
+| `-c, --config` | Path to config file (YAML or JSON) | Required |
+| `-t, --type` | Transport: `stdio`, `http`, `sse`, `stdio-http` | `stdio` |
+| `-p, --port` | Port for HTTP/SSE/stdio-http internal HTTP | `3000` |
+| `--host` | Host for HTTP/SSE/stdio-http internal HTTP | `localhost` |
+| `--no-cache` | Force reload config, bypass cache | `false` |
+| `--definitions-cache` | Read tool/prompt/skill definitions from a specific JSON or YAML cache file | Auto-derived from config path |
+| `--clear-definitions-cache` | Delete the effective definitions cache file before startup | `false` |
+
+## Notes
+
+- `mcp-proxy` reads YAML or JSON config files
+- environment variables use `${VAR_NAME}` interpolation
+- downstream stdio/http/sse servers can be mixed in one config
+- definitions cache is keyed by config content and mcp-proxy version
+
+## Related Packages
+
+- [@agimon-ai/scaffold-mcp](../scaffold-mcp) - Code scaffolding and templates
+- [@agimon-ai/architect-mcp](../architect-mcp) - Design patterns and code review
+- [@agimon-ai/aicode-toolkit](../../apps/aicode-toolkit) - Unified CLI toolkit
+
+---
+
+## License
+
+AGPL-3.0 © AgiflowIO