Content
# AIX MCP Server
[中文文档](./README.zh-CN.md)
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
```bash
npm install
npm run build
# stdio mode (for MCP clients)
npm start
# HTTP mode (starts web server + dashboard)
node dist/index.js http
```
### Docker
```bash
# 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:
```json
{
"mcpServers": {
"aix-mcp-server": {
"command": "node",
"args": ["/path/to/aix-mcp-server/dist/index.js"]
}
}
}
```
Or use HTTP mode (start the server first):
```json
{
"mcpServers": {
"aix-mcp-server": {
"url": "http://localhost:3080/mcp"
}
}
}
```
### Claude Desktop
Add to `claude_desktop_config.json`:
```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:
```typescript
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`:
```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`:
```json
{
"source": "./plugins/my-json-plugin.json",
"enabled": true
}
```
### Installing Plugins
```bash
# 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:
```json
{
"targets": [
{
"name": "remote-server",
"url": "http://other-mcp:3000/mcp",
"enabled": true,
"description": "Remote MCP server"
}
]
}
```
## Quality Checks
```bash
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](./docs/architecture.md) and [Registry Schema](./docs/registry-schema.md) for contributor-facing design details.
See [Cursor Integration Guide](./docs/cursor-integration.md) to configure this server for one project or all Cursor workspaces.
See [Technical Roadmap](./docs/roadmap.md) 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
```text
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
