npm package: @justanothermldude/meta-mcp-server
Description: Meta MCP server that wraps multiple backend MCP servers, exposing only 3 meta-tools to reduce context token consumption
Latest version: 0.1.14
Deprecated: This package has been deprecated. Use @justanothermldude/mcp-exec instead.

# @meta-mcp/server

Meta MCP server that wraps multiple backend MCP servers, exposing only 3 meta-tools to reduce context token consumption.

## Installation

```bash
npm install -g @meta-mcp/server
```

Or use via npx:

```bash
npx @meta-mcp/server
```

## Overview

When AI tools (Claude, Cursor, etc.) connect to many MCP servers, they load all tool schemas upfront - potentially 100+ tools consuming significant context tokens before any work begins.

Meta-MCP solves this by exposing only 3 tools:

| Tool | Purpose |
|------|---------|
| `list_servers` | List available backend servers (lightweight, no schemas) |
| `get_server_tools` | Fetch tools from a server with two-tier lazy loading |
| `call_tool` | Execute a tool on a backend server |

## Features

- **Lazy Loading**: Servers spawn only when first accessed
- **Two-Tier Tool Discovery**: Fetch summaries first (~100 tokens), then specific schemas on-demand
- **Connection Pool**: LRU eviction (max 20 connections) with idle cleanup (5 min)
- **Tool Caching**: Tool definitions cached per-server for session duration

## Quick Start

### 1. Configure Your AI Tool

Add meta-mcp to your AI tool's config file:

**Claude** (`~/.claude.json`):
```json
{
  "mcpServers": {
    "meta-mcp": {
      "command": "npx",
      "args": ["-y", "@meta-mcp/server"],
      "env": {
        "SERVERS_CONFIG": "~/.meta-mcp/servers.json"
      }
    }
  }
}
```

**Cursor** (`~/.cursor/mcp.json`):
```json
{
  "mcpServers": {
    "meta-mcp": {
      "command": "npx",
      "args": ["-y", "@meta-mcp/server"],
      "env": {
        "SERVERS_CONFIG": "~/.meta-mcp/servers.json"
      }
    }
  }
}
```

### 2. Configure Backend Servers

Create `~/.meta-mcp/servers.json`:

```json
{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "/home/user"],
      "description": "File system access"
    },
    "github": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-github"],
      "env": {
        "GITHUB_TOKEN": "your-token"
      },
      "description": "GitHub integration"
    }
  }
}
```

### 3. Restart Your AI Tool

Restart Claude/Cursor to load the new configuration.

## API Reference

### list_servers

List all available backend MCP servers.

```typescript
list_servers(filter?: string): ServerInfo[]
```

**Parameters:**
- `filter` (optional): Filter servers by name pattern

**Returns:**
```typescript
[
  { name: "filesystem", description: "File system access" },
  { name: "github", description: "GitHub integration" }
]
```

### get_server_tools

Fetch tools from a backend server with two-tier lazy loading.

```typescript
get_server_tools(options: {
  server_name: string;
  summary_only?: boolean;  // Only fetch names/descriptions (~100 tokens)
  tools?: string[];        // Fetch specific tool schemas
}): ToolDefinition[]
```

**Examples:**

```typescript
// Get all tool summaries (lightweight)
get_server_tools({ server_name: "filesystem", summary_only: true })
// => [{ name: "read_file", description: "..." }, ...]

// Get specific tool schemas
get_server_tools({ server_name: "filesystem", tools: ["read_file", "write_file"] })
// => [{ name: "read_file", inputSchema: {...} }, ...]

// Get all tools with full schemas (backward compatible)
get_server_tools({ server_name: "filesystem" })
// => [{ name: "read_file", inputSchema: {...} }, ...]
```

### call_tool

Execute a tool on a backend server.

```typescript
call_tool(options: {
  server_name: string;
  tool_name: string;
  arguments?: Record<string, unknown>;
}): CallToolResult
```

**Example:**

```typescript
call_tool({
  server_name: "filesystem",
  tool_name: "read_file",
  arguments: { path: "/tmp/test.txt" }
})
// => { content: [{ type: "text", text: "file contents..." }] }
```

## Programmatic Usage

```typescript
import { createServer } from '@meta-mcp/server';
import { ServerPool, ToolCache, createConnection, getServerConfig } from '@meta-mcp/core';

// Create connection factory
const connectionFactory = async (serverId: string) => {
  const config = getServerConfig(serverId);
  if (!config) throw new Error(`Server not found: ${serverId}`);
  return createConnection(config);
};

// Initialize components
const pool = new ServerPool(connectionFactory);
const toolCache = new ToolCache();

// Create server
const { server, shutdown } = createServer(pool, toolCache);

// Connect to transport
await server.connect(transport);

// Graceful shutdown
await shutdown();
await server.close();
```

## CLI Usage

```bash
# Start the server (stdio transport)
meta-mcp-server

# Show version
meta-mcp-server --version

# Show help
meta-mcp-server --help
```

## Environment Variables

| Variable | Default | Description |
|----------|---------|-------------|
| `SERVERS_CONFIG` | `~/.meta-mcp/servers.json` | Path to backend servers configuration |
| `MAX_CONNECTIONS` | `20` | Maximum concurrent server connections |
| `IDLE_TIMEOUT_MS` | `300000` | Idle connection cleanup timeout (5 min) |
| `MCP_DEFAULT_TIMEOUT` | none | Global timeout for MCP tool calls (ms). Per-server `timeout` takes precedence. |

## Token Optimization

Meta-MCP provides 87-91% token savings through two-tier lazy loading:

1. **Discovery Phase**: `list_servers()` returns only server names/descriptions
2. **Summary Phase**: `get_server_tools({ summary_only: true })` returns tool names/descriptions (~100 tokens for 25 tools)
3. **Schema Phase**: `get_server_tools({ tools: ["specific_tool"] })` fetches only needed schemas
4. **Execution Phase**: `call_tool()` executes with full context only when needed

## License

MIT