AIX MCP Server

中文文档

An extensible Model Context Protocol (MCP) server with a plugin system, proxy forwarding, Web Dashboard, and a built-in service registry.

Features

• Dual Transport — stdio (for Cursor / Claude Desktop) and Streamable HTTP
• Plugin System — 7 built-in utility plugins; extend via npm packages, local paths, or JSON files
• Proxy Forwarding — Aggregate multiple remote MCP servers into a single endpoint
• Web Dashboard — Manage plugins, proxies, and logs through a visual interface
• Service Registry — Pre-loaded catalog of popular MCP services with one-click install and config copy
• LLM-Powered Search — AI-driven discovery and recommendations for MCP services
• Docker Ready — Multi-stage build, works out of the box

Preview

Quick Start

Local

npm install
npm run build

# stdio mode (for MCP clients)
npm start

# HTTP mode (starts web server + dashboard)
node dist/index.js http

Docker

# Build and start (detached)
docker compose up --build -d

# View logs
docker compose logs -f

# Stop
docker compose down

The service listens on http://localhost:3080 by default.

Built-in Plugins

Plugin	Tools	Description
calculator	calculator	Math expression evaluation
crypto	hash-text, random-uuid, random-string	Hashing, UUID, random strings
datetime	current-time, format-time	Current time, time formatting
filesystem	list-files, read-file + Resource	File listing, reading, file resource
hello-json	hello-json + Resource	Declarative JSON-authored plugin example
system	run-command + Resource	Shell command execution, system info resource
text-utils	json-format, base64, text-stats	JSON formatting, Base64 encode/decode, text stats

MCP Client Configuration

Cursor

Add to your Cursor MCP settings:

{
  "mcpServers": {
    "aix-mcp-server": {
      "command": "node",
      "args": ["/path/to/aix-mcp-server/dist/index.js"]
    }
  }
}

Or use HTTP mode (start the server first):

{
  "mcpServers": {
    "aix-mcp-server": {
      "url": "http://localhost:3080/mcp"
    }
  }
}

Claude Desktop

Add to claude_desktop_config.json:

{
  "mcpServers": {
    "aix-mcp-server": {
      "command": "node",
      "args": ["/path/to/aix-mcp-server/dist/index.js"]
    }
  }
}

Plugin Development

Create a TypeScript file that default-exports an object conforming to the McpPlugin interface:

import { z } from "zod";
import type { McpPlugin } from "aix-mcp-server/plugin";

const plugin: McpPlugin = {
  name: "my-plugin",
  description: "My custom plugin",
  register(server) {
    server.registerTool("my-tool", {
      title: "My Tool",
      description: "Does something useful",
      inputSchema: z.object({
        input: z.string().describe("Input value"),
      }),
    }, async ({ input }) => {
      return { content: [{ type: "text", text: `Result: ${input}` }] };
    });
  },
};

export default plugin;

See examples/mcp-plugin-example/ for a complete example.

JSON Plugins

You can also create lightweight local MCP plugins using only JSON, similar to sharing a userscript. JSON plugins are declarative and do not execute arbitrary JavaScript. They currently support template/json tool responses and static resources.

Create plugins/my-json-plugin.json:

{
  "schemaVersion": 1,
  "name": "my-json-plugin",
  "description": "A declarative JSON MCP plugin",
  "tools": [
    {
      "name": "hello",
      "title": "Hello",
      "description": "Return a greeting",
      "inputSchema": {
        "type": "object",
        "required": ["name"],
        "properties": {
          "name": { "type": "string", "description": "Name to greet" }
        }
      },
      "response": {
        "type": "template",
        "text": "Hello {{name}}!"
      }
    }
  ]
}

Then add it to mcp-plugins.json:

{
  "source": "./plugins/my-json-plugin.json",
  "enabled": true
}

Installing Plugins

# Via CLI
node dist/cli.js add ./path/to/plugin
node dist/cli.js add some-npm-package

# Or edit mcp-plugins.json directly

Proxy Configuration

Edit mcp-proxy.json to add remote MCP servers:

{
  "targets": [
    {
      "name": "remote-server",
      "url": "http://other-mcp:3000/mcp",
      "enabled": true,
      "description": "Remote MCP server"
    }
  ]
}

Quality Checks

npm test
npm run registry:validate

registry:validate checks mcp-registry.json and configured JSON plugins before you open a pull request.

Architecture

See Architecture Notes and Registry Schema for contributor-facing design details.

See Cursor Integration Guide to configure this server for one project or all Cursor workspaces.

See Technical Roadmap for the planned v1.1, v1.2, and v2.0 evolution.

Troubleshooting

• http://localhost:3080/mcp returns Missing or invalid session ID: this is expected when opening the MCP endpoint directly in a browser. Use the Dashboard at http://localhost:3080, or connect through an MCP client.
• Dashboard changes do not appear: rebuild and restart the server or container after changing TypeScript, plugins, or config files.
• JSON plugin fails to load: run npm run registry:validate to get an exact field path for the invalid JSON.
• Sandbox upgrade fails: inspect the failed check and its Fix message in the Dashboard, then rerun sandbox validation.

Project Structure

aix-mcp-server/
├── src/
│   ├── index.ts          # Entry (stdio / HTTP transport)
│   ├── cli.ts            # Plugin management CLI
│   ├── loader.ts         # Plugin loader
│   ├── plugin.ts         # Plugin interface
│   ├── proxy.ts          # Proxy forwarding
│   ├── registry.ts       # Service registry
│   ├── llm.ts            # LLM provider integration
│   ├── plugins/          # Built-in plugins
│   │   ├── calculator.ts
│   │   ├── crypto.ts
│   │   ├── datetime.ts
│   │   ├── filesystem.ts
│   │   ├── system.ts
│   │   └── text-utils.ts
│   └── web/
│       ├── api.ts        # Dashboard API routes
│       └── dashboard.html
├── mcp-plugins.json      # Plugin configuration
├── mcp-proxy.json        # Proxy configuration
├── mcp-registry.json     # Service registry data
├── llm-config.json       # LLM provider configuration
├── docker-compose.yml
├── Dockerfile
└── package.json

License

MIT