@agiflowai/one-mcp 0.2.3 → 0.2.5

package/README.md

@@ -1,95 +1,59 @@
 # @agiflowai/one-mcp
 
-A unified MCP (Model Context Protocol) proxy server that enables **progressive tool discovery** to dramatically reduce token usage when working with multiple MCP servers.
+> MCP proxy server for progressive tool discovery and reduced token usage
 
-## The Problem: MCP Token Bloat
+Connect to multiple MCP servers through a single proxy that loads tools on-demand, reducing initial token usage by 90%+.
 
-When connecting to multiple MCP servers directly, AI agents must load ALL tools from ALL servers into their context window at startup. This creates massive token overhead:
+## The Problem
+
+When connecting to multiple MCP servers directly, AI agents load ALL tools from ALL servers at startup:
 
-**Example: 10 MCP Servers**
 ```
-Server 1: 20 tools × 200 tokens = 4,000 tokens
-Server 2: 15 tools × 200 tokens = 3,000 tokens
-Server 3: 30 tools × 200 tokens = 6,000 tokens
-...
-Total: ~40,000+ tokens consumed BEFORE you even start coding
+10 MCP Servers:
+  Server 1: 20 tools × 200 tokens = 4,000 tokens
+  Server 2: 15 tools × 200 tokens = 3,000 tokens
+  Server 3: 30 tools × 200 tokens = 6,000 tokens
+  ...
+  Total: ~40,000+ tokens consumed BEFORE you even start coding
 ```
 
-This consumes a significant portion of your context window with tool descriptions you may never use in that session.
-
-## The Solution: Progressive Discovery
-
-one-mcp acts as a **smart proxy** that only loads tool descriptions when needed:
-
-1. **Initial Connection**: Agent sees only 2 meta-tools (`describe_tools` and `use_tool`)
-   - Token cost: ~400 tokens (vs 40,000+ tokens)
+This wastes context window on tool descriptions you may never use.
 
-2. **Discovery on Demand**: Agent calls `describe_tools` only for servers/tools it needs
-   - Example: `describe_tools(["filesystem"])` loads only filesystem server tools
-   - Token cost: ~4,000 tokens (only what you need, when you need it)
-
-3. **Tool Execution**: Agent calls `use_tool` to execute tools through the proxy
-   - one-mcp routes the call to the correct server
-   - No token overhead - just execution
-
-**Result: 90%+ reduction in initial token usage**
+## The Solution
 
-## How It Works
+one-mcp acts as a smart proxy with progressive discovery:
 
 ```
-Traditional Approach (High Token Cost):
-┌─────────────────┐
-│  AI Agent       │ ← Loads ALL tools from ALL servers (40,000+ tokens)
-├─────────────────┤
-│ MCP Server 1    │ → 20 tools
-│ MCP Server 2    │ → 15 tools
-│ MCP Server 3    │ → 30 tools
-│ ...             │
-└─────────────────┘
-
-Progressive Discovery (Low Token Cost):
-┌─────────────────┐
-│  AI Agent       │ ← Loads only 2 meta-tools (400 tokens)
-├─────────────────┤
-│  one-mcp        │ ← Proxies to servers on-demand
-│  (2 tools)      │
-└────────┬────────┘
-         │ Connects to servers as needed
-    ┌────┴─────┬──────────┬─────────┐
-    │ Server 1 │ Server 2 │ Server 3│
-    └──────────┴──────────┴─────────┘
+Traditional (High Token Cost):          Progressive Discovery (Low Token Cost):
+┌─────────────────┐                    ┌─────────────────┐
+│  AI Agent       │ ← 40,000+ tokens   │  AI Agent       │ ← 400 tokens
+├─────────────────┤                    ├─────────────────┤
+│ Server 1 (20)   │                    │  one-mcp        │ ← 2 meta-tools
+│ Server 2 (15)   │                    │  (proxy)        │
+│ Server 3 (30)   │                    └────────┬────────┘
+│ ...             │                             │ loads on-demand
+└─────────────────┘                        ┌────┴────┬────────┐
+                                           │ Srv 1   │ Srv 2  │ ...
+                                           └─────────┴────────┘
 ```
 
-## Key Benefits
-
-- **Massive Token Savings** - 90%+ reduction in initial context usage
-- **Faster Startup** - Agent ready in milliseconds, not seconds
-- **Scale Infinitely** - Add 100+ MCP servers without bloating context
-- **Pay-as-you-go** - Only load tools when actually needed
-- **Better Context Budget** - Save tokens for actual code and conversation
-- **Centralized Config** - Manage all servers from one YAML/JSON file
+1. **Initial**: Agent sees only 2 meta-tools (`describe_tools`, `use_tool`) - ~400 tokens
+2. **Discovery**: Agent calls `describe_tools` for specific servers when needed
+3. **Execution**: Agent calls `use_tool` to run tools through the proxy
 
-## Installation
+**Result: 90%+ reduction in initial token usage**
 
-```bash
-npm install -g @agiflowai/one-mcp
-# or
-pnpm add -g @agiflowai/one-mcp
-# or
-yarn global add @agiflowai/one-mcp
-```
+---
 
 ## Quick Start
 
-### 1. Initialize Configuration
-
-Create an MCP configuration file:
+### 1. Create Configuration
 
 ```bash
 npx @agiflowai/one-mcp init
 ```
 
-This creates a `mcp-config.yaml` file with example servers:
+This creates `mcp-config.yaml`:
 
 ```yaml
 mcpServers:
@@ -102,20 +66,19 @@ mcpServers:
     config:
       instruction: "Access files in the Documents folder"
 
-  web-search:
-    url: https://example.com/mcp/search
-    type: sse
-    headers:
-      Authorization: "Bearer ${API_KEY}"
+  scaffold-mcp:
+    command: npx
+    args:
+      - -y
+      - "@agiflowai/scaffold-mcp"
+      - "mcp-serve"
     config:
-      instruction: "Search the web for information"
+      instruction: "Scaffold projects and features"
 ```
 
 ### 2. Configure Your Agent
 
-Add one-mcp to your AI coding tool's MCP configuration:
-
-**For Claude Code:**
+Add to your MCP config (`.mcp.json`, `.cursor/mcp.json`, etc.):
 
 ```json
 {
@@ -128,33 +91,20 @@ Add one-mcp to your AI coding tool's MCP configuration:
 }
 ```
 
-**For Cursor:**
+### 3. Start Using
 
-```json
-{
-  "mcpServers": {
-    "one-mcp": {
-      "command": "npx",
-      "args": ["-y", "@agiflowai/one-mcp", "mcp-serve", "--config", "./mcp-config.yaml"]
-    }
-  }
-}
-```
-
-### 3. Start Using Tools
+Your agent now has access to all tools from all configured servers through one connection.
 
-Your agent now has access to all tools from all configured servers through the single one-mcp connection!
+---
 
 ## Configuration
 
-### Config File Format
-
-one-mcp supports the standard Claude Code MCP configuration format:
+### Server Types
 
 ```yaml
 mcpServers:
   # Stdio server (local command)
-  server-name:
+  local-server:
     command: npx
     args:
       - -y
@@ -162,11 +112,7 @@ mcpServers:
     env:
       API_KEY: "${MY_API_KEY}"
     config:
-      instruction: "Custom instruction for this server"
-      # Optional: Block specific tools from being listed or executed
-      toolBlacklist:
-        - dangerous_tool
-        - another_blocked_tool
+      instruction: "Description for the AI agent"
 
   # HTTP/SSE server (remote)
   remote-server:
@@ -175,20 +121,18 @@ mcpServers:
     headers:
       Authorization: "Bearer ${TOKEN}"
     config:
-      instruction: "Remote server instruction"
-      toolBlacklist:
-        - risky_operation
+      instruction: "Remote server description"
 
-  # Disabled server (will be skipped)
+  # Disabled server (skipped)
   disabled-server:
     command: node
     args: ["server.js"]
     disabled: true
 ```
 
-### Environment Variable Interpolation
+### Environment Variables
 
-Use `${VAR_NAME}` syntax to interpolate environment variables:
+Use `${VAR_NAME}` syntax:
 
 ```yaml
 mcpServers:
@@ -196,197 +140,142 @@ mcpServers:
     command: npx
     args:
       - "@mycompany/mcp-server"
-      - "${HOME}/data"  # Expands to /Users/username/data
+      - "${HOME}/data"           # Expands to /Users/username/data
     env:
-      API_KEY: "${MY_API_KEY}"  # Reads from environment
+      API_KEY: "${MY_API_KEY}"   # Reads from environment
 ```
 
 ### Tool Blacklisting
 
-Control which tools from an MCP server are accessible by using the `toolBlacklist` configuration. Blacklisted tools will:
-- Not appear in `list-tools` output
-- Not be shown in `describe_tools` responses
-- Raise an error if attempted to be executed via `use_tool`
-
-This is useful for:
-- **Security**: Block dangerous operations (e.g., `write_file`, `delete_file`)
-- **Compliance**: Restrict tools that don't meet your policies
-- **Simplification**: Hide tools you don't want agents to use
-
-**Example:**
+Block specific tools from being listed or executed:
 
 ```yaml
 mcpServers:
   filesystem:
     command: npx
-    args:
-      - -y
-      - "@modelcontextprotocol/server-filesystem"
-      - "/workspace"
+    args: ["-y", "@modelcontextprotocol/server-filesystem", "/workspace"]
     config:
       instruction: "File system access (read-only)"
       toolBlacklist:
         - write_file
         - create_directory
-        - move_file
+        - delete_file
 ```
 
-**Behavior:**
-- Agents will only see read-only tools like `read_file`, `list_directory`
-- Attempting to call `write_file` will return an error: `Tool "write_file" is blacklisted on server "filesystem" and cannot be executed.`
+Blacklisted tools:
+- Won't appear in tool listings
+- Return an error if called
 
-### Tool Description Formatting
+### Compact Tool Descriptions
 
-Control how tool information is displayed by using the `omitToolDescription` configuration flag. This helps reduce token usage when full descriptions aren't needed.
-
-**Default behavior (omitToolDescription: false or not set):**
-```
-server-name:
-  - tool_name1: Full description of what this tool does...
-  - tool_name2: Another detailed description...
-```
-
-**Compact mode (omitToolDescription: true):**
-```
-server-name:
-  tool_name1, tool_name2, tool_name3
-```
-
-**Example:**
+Reduce token usage by omitting verbose descriptions:
 
 ```yaml
 mcpServers:
   filesystem:
     command: npx
-    args:
-      - -y
-      - "@modelcontextprotocol/server-filesystem"
-      - "/workspace"
+    args: ["-y", "@modelcontextprotocol/server-filesystem", "/workspace"]
     config:
-      instruction: "File system access"
-      omitToolDescription: true  # Show only tool names, not descriptions
+      omitToolDescription: true  # Show only tool names
 ```
 
-**Benefits:**
-- **Reduced Token Usage**: Save context window space by omitting verbose descriptions
-- **Faster Discovery**: Quickly scan available tool names without reading full descriptions
-- **Cleaner Output**: More compact tool listings for familiar servers
-
-**When to use:**
-- You're already familiar with the server's tools
-- Working with servers that have many tools with long descriptions
-- Trying to conserve context window tokens
-- Need a quick overview of available tool names
-
-## CLI Commands
-
-### `mcp-serve`
-
-Start the MCP server:
-
-```bash
-npx @agiflowai/one-mcp mcp-serve [options]
-
-Options:
-  -c, --config <path>  Path to local config file (YAML or JSON)
-  --no-cache           Force reload configuration from source, bypassing cache
-  -t, --type <type>    Transport mode: stdio (default), http, sse
-  -p, --port <number>  Port for HTTP/SSE transport (default: 3000)
-  --host <host>        Host to bind to (HTTP/SSE only, default: localhost)
+**Default output:**
 ```
-
-### `init`
-
-Initialize an MCP configuration file:
-
-```bash
-npx @agiflowai/one-mcp init [options]
-
-Options:
-  -o, --output <path>  Output file path (default: mcp-config.yaml)
-  --json              Generate JSON config instead of YAML
-  -f, --force         Overwrite existing config file
+filesystem:
+  - read_file: Read contents of a file at the specified path...
+  - list_directory: List all files and directories...
 ```
 
-### `list-tools`
-
-List all available tools from configured servers:
-
-```bash
-npx @agiflowai/one-mcp list-tools --config ./mcp-config.yaml
+**With omitToolDescription:**
 ```
-
-### `describe-tools`
-
-Get detailed information about specific tools:
-
-```bash
-npx @agiflowai/one-mcp describe-tools \
-  --config ./mcp-config.yaml \
-  --tools tool1,tool2
+filesystem:
+  read_file, list_directory, search_files
 ```
 
-### `use-tool`
-
-Execute a tool directly from CLI:
-
-```bash
-npx @agiflowai/one-mcp use-tool \
-  --config ./mcp-config.yaml \
-  --tool-name read_file \
-  --args '{"path": "/path/to/file"}'
-```
+---
 
 ## MCP Tools
 
-When running as an MCP server, one-mcp provides these tools:
+When running as an MCP server, one-mcp provides:
 
-### `mcp__one-mcp__describe_tools`
+### `describe_tools`
 
-Get detailed information about available tools from connected servers.
+Get information about available tools:
 
-**Input:**
 ```json
 {
-  "toolNames": ["tool1", "tool2"],
-  "serverName": "optional-server-name"
+  "toolNames": ["read_file", "write_file"],
+  "serverName": "filesystem"  // optional
 }
 ```
 
-### `mcp__one-mcp__use_tool`
+### `use_tool`
 
-Execute a tool from any connected server.
+Execute a tool from any connected server:
 
-**Input:**
 ```json
 {
   "toolName": "read_file",
   "toolArgs": {
     "path": "/path/to/file"
   },
-  "serverName": "optional-server-name"
+  "serverName": "filesystem"  // optional, auto-detected if unique
 }
 ```
 
-## Use Cases
+---
+
+## CLI Commands
+
+```bash
+# Start MCP server (stdio, for Claude Code/Cursor)
+npx @agiflowai/one-mcp mcp-serve --config ./mcp-config.yaml
 
-### 1. Simplify Multi-Server Setup
+# Start with HTTP transport
+npx @agiflowai/one-mcp mcp-serve --config ./mcp-config.yaml --type http --port 3000
 
-Instead of configuring 10+ MCP servers individually in your agent:
+# Initialize config file
+npx @agiflowai/one-mcp init --output mcp-config.yaml
 
-**Before:**
+# List all tools from configured servers
+npx @agiflowai/one-mcp list-tools --config ./mcp-config.yaml
+
+# Get tool details
+npx @agiflowai/one-mcp describe-tools --config ./mcp-config.yaml --tools read_file,write_file
+
+# Execute a tool directly
+npx @agiflowai/one-mcp use-tool --config ./mcp-config.yaml --tool-name read_file --args '{"path": "/tmp/test.txt"}'
+```
+
+### Server Options
+
+| Option | Description | Default |
+|--------|-------------|---------|
+| `-c, --config` | Path to config file (YAML or JSON) | Required |
+| `-t, --type` | Transport: `stdio`, `http`, `sse` | `stdio` |
+| `-p, --port` | Port for HTTP/SSE | `3000` |
+| `--host` | Host for HTTP/SSE | `localhost` |
+| `--no-cache` | Force reload config, bypass cache | `false` |
+
+---
+
+## Use Cases
+
+### 1. Consolidate Multiple Servers
+
+**Before (10 server configs):**
 ```json
 {
   "mcpServers": {
     "filesystem": { "command": "npx", "args": ["..."] },
     "database": { "command": "npx", "args": ["..."] },
-    "web-search": { "command": "npx", "args": ["..."] },
-    // ... 7 more servers
+    "web-search": { "command": "npx", "args": ["..."] }
+    // ... 7 more
   }
 }
 ```
 
-**After:**
+**After (1 config):**
 ```json
 {
   "mcpServers": {
@@ -398,15 +287,7 @@ Instead of configuring 10+ MCP servers individually in your agent:
 }
 ```
 
-### 2. Centralized Configuration Management
-
-Manage all MCP servers from a single YAML/JSON file that can be:
-- Version controlled
-- Shared across teams
-- Hosted remotely
-- Environment-specific
-
-### 3. Mix Local and Remote Servers
+### 2. Mix Local and Remote Servers
 
 ```yaml
 mcpServers:
@@ -423,9 +304,7 @@ mcpServers:
       Authorization: "Bearer ${COMPANY_TOKEN}"
 ```
 
-### 4. Dynamic Configuration
-
-Load different configs based on environment:
+### 3. Environment-Specific Configs
 
 ```bash
 # Development
@@ -435,21 +314,7 @@ npx @agiflowai/one-mcp mcp-serve --config ./mcp-dev.yaml
 npx @agiflowai/one-mcp mcp-serve --config ./mcp-prod.yaml
 ```
 
-## Development
-
-```bash
-# Install dependencies
-pnpm install
-
-# Build
-pnpm build
-
-# Run tests
-pnpm test
-
-# Run in development mode
-pnpm dev
-```
+---
 
 ## Architecture
 
@@ -458,27 +323,17 @@ pnpm dev
 │  AI Agent       │
 │  (Claude/etc)   │
 └────────┬────────┘
-         │ Single MCP Connection
+         │ Single MCP Connection (2 tools)
          │
 ┌────────▼────────────────────────────┐
-│                                     │
 │         @agiflowai/one-mcp          │
 │                                     │
-│  ┌─────────────────────────────┐   │
-│  │  ConfigFetcherService       │   │
-│  │  - Load YAML/JSON configs   │   │
-│  │  - Merge strategies         │   │
-│  │  - Environment interpolation│   │
-│  └─────────────────────────────┘   │
-│                                     │
-│  ┌─────────────────────────────┐   │
-│  │  McpClientManagerService    │   │
-│  │  - Connect to MCP servers   │   │
-│  │  - Manage connections       │   │
-│  │  - Route tool calls         │   │
-│  └─────────────────────────────┘   │
-│                                     │
-└──────┬──────┬───────┬──────────────┘
+│  • Load configs (YAML/JSON)         │
+│  • Environment interpolation        │
+│  • Connect to servers on-demand     │
+│  • Route tool calls                 │
+│  • Apply blacklists                 │
+└──────┬──────┬───────┬───────────────┘
        │      │       │
        │      │       │ Multiple MCP Connections
        │      │       │
@@ -489,12 +344,16 @@ pnpm dev
    └──────┘ └──────┘ └──────────┘
 ```
 
-## License
-
-AGPL-3.0 © AgiflowIO
+---
 
 ## Related Packages
 
-- [@agiflowai/scaffold-mcp](../scaffold-mcp) - Scaffolding and templates
-- [@agiflowai/architect-mcp](../architect-mcp) - Architecture patterns and code review
-- [@agiflowai/aicode-toolkit](../../apps/aicode-toolkit) - Unified CLI toolkit
+- [@agiflowai/scaffold-mcp](../scaffold-mcp) - Code scaffolding and templates
+- [@agiflowai/architect-mcp](../architect-mcp) - Design patterns and code review
+- [@agiflowai/aicode-toolkit](../../apps/aicode-toolkit) - Unified CLI toolkit
+
+---
+
+## License
+
+AGPL-3.0 © AgiflowIO