MCP Learning Adapter 🚀

An intelligent adapter that learns MCP server APIs and optimizes token usage by 80% through automated schema learning and response filtering.

Overview

This adapter sits between Claude Desktop (or any MCP client) and your MCP servers, automatically learning their response patterns and filtering out noise. Instead of sending massive JSON responses with redundant fields, it intelligently reduces token consumption while maintaining full functionality.

Key Benefits

80% reduction in input tokens - Dramatically lower costs and faster responses
Self-learning - Automatically discovers and categorizes API response patterns
Smart filtering - Pins important fields, removes noise, ghosts redundant data
Drop-in replacement - Works with existing MCP servers (Node.js-based)
Community-driven - Share your learned schemas in registry.json

Architecture

┌─────────────┐
│   Claude    │
│  Desktop    │
└──────┬──────┘
       │
       ▼
┌─────────────────────┐
│  Learning Adapter   │  ← You are here
│  - Brain (learning) │
│  - Registry (cache) │
│  - Proxy (filter)   │
└──────┬──────────────┘
       │
       ▼
┌─────────────────────┐
│   MCP Servers       │
│  (ado, dovetail,    │
│   filesystem, etc.) │
└─────────────────────┘

Quick Start

1. Install Dependencies

npm install

2. Configure Servers

Copy the example configuration:

cp config/servers.json.example config/servers.json

Edit config/servers.json with your settings:

{
  "adapter": {
    "openaiApiKey": "sk-your-openai-api-key-here"
  },
  "servers": {
    "ado": {
      "command": "node",
      "args": [
        "/path/to/azure-devops-mcp/dist/index.js",
        "your-org-name"
      ],
      "env": {
        "project": "your-project-name",
        "organization": "your-org-name"
      }
    },
    "dovetail-mcp": {
      "command": "node",
      "args": ["/path/to/dovetail-mcp/dist/index.js"],
      "env": {
        "DOVETAIL_API_TOKEN": "your-api-token-here"
      }
    }
  }
}

3. Set Up Claude Desktop Integration

Create or edit .vscode/mcp.json in your project:

{
  "mcpServers": {
    "learning-adapter": {
      "command": "npx",
      "args": [
        "tsx",
        "/path/to/ado-learning-adapter/src/adaptive-proxy.ts"
      ],
      "env": {}
    }
  }
}

Or add to your Claude Desktop config (~/Library/Application Support/Claude/claude_desktop_config.json on macOS):

{
  "mcpServers": {
    "learning-adapter": {
      "command": "npx",
      "args": [
        "tsx",
        "/path/to/ado-learning-adapter/src/adaptive-proxy.ts"
      ]
    }
  }
}

4. Start Using

The adapter will automatically:

Connect to your configured MCP servers
Learn response patterns as you use them
Build optimized schemas in config/registry.json
Reduce token usage progressively

How It Learns 🧠

The adapter uses GPT 5.1 to analyze API responses and categorize fields into three types:

Pinned 📌 - Essential fields always included (e.g., id, title, state)
Noise 🔇 - Redundant fields removed (e.g., _links, imageUrl, descriptor)
Ghosts 👻 - Fields summarized or count-only (e.g., long lists, nested objects)

After a few API calls, the adapter learns the optimal schema and applies it automatically.

Token Savings Example 📊

Before (Raw Response):

{
  "id": 123,
  "fields": {
    "System.Title": "Fix bug",
    "System.State": "Active",
    "System.AssignedTo": {
      "displayName": "John Doe",
      "url": "https://...",
      "_links": { "avatar": { "href": "..." } },
      "id": "guid-here",
      "uniqueName": "john@...",
      "imageUrl": "https://...",
      "descriptor": "..."
    },
    "_links": { ... }
  }
}

~500 tokens

After (Learned & Filtered):

{
  "id": 123,
  "fields": {
    "System.Title": "Fix bug",
    "System.State": "Active",
    "System.AssignedTo": { "displayName": "John Doe" }
  }
}

~100 tokens (80% reduction!)

Contributing 🤝

If you use this adapter and it learns schemas for your MCP servers, please contribute back!

Use the adapter with your MCP servers
Let it learn and optimize (check config/registry.json)
Create a PR with your learned schemas
Help the community save tokens and costs! ❤️

The more we share, the better the adapter becomes for everyone.

Roadmap 🛣️

Current Support

✅ Node.js-based MCP servers
✅ Automatic schema learning
✅ Response filtering and optimization
✅ Multi-server support

Coming Soon

🔜 HTTP/REST MCP servers
🔜 Sandbox-based MCP servers
🔜 Pre-built schema library
🔜 Configuration UI
🔜 Performance analytics dashboard

Configuration Reference ⚙️

servers.json Structure

{
  "adapter": {
    "openaiApiKey": "string"  // Required for learning (uses GPT 5.1)
  },
  "servers": {
    "server-name": {
      "command": "string",    // Command to run (e.g., "node", "npx")
      "args": ["string"],     // Arguments to pass
      "env": {                // Environment variables
        "KEY": "value"
      }
    }
  }
}

registry.json Structure

This file is auto-generated but you can edit it:

{
  "tool_name": {
    "status": "optimized",  // "learning" or "optimized"
    "schema": {
      "pinned": ["field.path"],   // Always include
      "noise": ["field.path"],    // Always exclude
      "ghosts": ["field.path"]    // Summarize/count
    }
  }
}

Troubleshooting

Adapter not connecting?

Verify your MCP server paths in config/servers.json
Check that servers run independently: node /path/to/server/index.js
Look for errors in the console output

Not learning?

Ensure openaiApiKey is set in config/servers.json
The adapter needs GPT 5.1 access to learn
Check config/registry.json to see learning progress

High token usage still?

Learning takes a few API calls (typically 3-5 calls per tool)
Check if tool status is "optimized" in registry.json
Some tools may need manual schema adjustments

License 📝

See LICENSE for details.

Acknowledgments 🙏

Built for the MCP community. Special thanks to all contributors who share their learned schemas!

Questions? Open an issue! Want to contribute? PRs welcome! Love it? Star the repo! ⭐

Learning Adapter