内容
# AIX MCP 服务器
[中文文档](./README.zh-CN.md)
一款可扩展的模型上下文协议（MCP）服务器，具备插件系统、代理转发、Web 控制面板和内置服务注册中心。
## 功能特点
- **双重传输** — stdio（适用于 Cursor / Claude Desktop）和可流式传输的 HTTP
- **插件系统** — 7 个内置实用插件；可通过 npm 包、本地路径或 JSON 文件扩展
- **代理转发** — 将多个远程 MCP 服务器聚合到单个端点
- **Web 控制面板** — 通过可视化界面管理插件、代理和日志
- **服务注册中心** — 预加载的热门 MCP 服务目录，支持一键安装和配置复制
- **LLM 驱动的搜索** — AI 驱动的 MCP 服务发现和推荐
- **Docker 就绪** — 多阶段构建，开箱即用
## 预览
## 快速开始
### 本地
```bash
npm install
npm run build
# stdio 模式（适用于 MCP 客户端）
npm start
# HTTP 模式（启动 Web 服务器 + 控制面板）
node dist/index.js http
```
### Docker
```bash
# 构建并启动（分离模式）
docker compose up --build -d
# 查看日志
docker compose logs -f
# 停止
docker compose down
```
服务默认监听 `http://localhost:3080`。
## 内置插件
| 插件 | 工具 | 描述 |
| -------- | ------- | ------------- |
| **计算器** | `计算器` | 数学表达式求值 |
| **加密** | `哈希文本`、`随机 UUID`、`随机字符串` | 哈希、UUID、随机字符串 |
| **日期时间** | `当前时间`、`格式化时间` | 当前时间、时间格式化 |
| **文件系统** | `列出文件`、`读取文件` + 资源 | 文件列表、读取、文件资源 |
| **Hello JSON** | `hello-json` + 资源 | 声明式 JSON 插件示例 |
| **系统** | `运行命令` + 资源 | Shell 命令执行、系统信息资源 |
| **文本工具** | `JSON 格式化`、`Base64`、`文本统计` | JSON 格式化、Base64 编码/解码、文本统计 |
## MCP 客户端配置
### Cursor
在您的 Cursor MCP 设置中添加：
```json
{
"mcpServers": {
"aix-mcp-server": {
"command": "node",
"args": ["/path/to/aix-mcp-server/dist/index.js"]
}
}
}
```
或使用 HTTP 模式（首先启动服务器）：
```json
{
"mcpServers": {
"aix-mcp-server": {
"url": "http://localhost:3080/mcp"
}
}
}
```
### Claude Desktop
添加到 `claude_desktop_config.json`：
```json
{
"mcpServers": {
"aix-mcp-server": {
"command": "node",
"args": ["/path/to/aix-mcp-server/dist/index.js"]
}
}
}
```
## 插件开发
创建一个 TypeScript 文件，默认导出一个符合 `McpPlugin` 接口的对象：
```typescript
import { z } from "zod";
import type { McpPlugin } from "aix-mcp-server/plugin";
const plugin: McpPlugin = {
name: "my-plugin",
description: "我的自定义插件",
register(server) {
server.registerTool("my-tool", {
title: "我的工具",
description: "执行某些有用的操作",
inputSchema: z.object({
input: z.string().describe("输入值"),
}),
}, async ({ input }) => {
return { content: [{ type: "text", text: `结果：${input}` }] };
});
},
};
export default plugin;
```
参见 `examples/mcp-plugin-example/` 获取完整示例。
### JSON 插件
您还可以使用 JSON 创建轻量级本地 MCP 插件，类似于共享用户脚本。JSON 插件是声明式的，不执行任意 JavaScript 代码。目前，它们支持模板/JSON 工具响应和静态资源。
创建 `plugins/my-json-plugin.json`：
```json
{
"schemaVersion": 1,
"name": "my-json-plugin",
"description": "声明式 JSON MCP 插件",
"tools": [
{
"name": "hello",
"title": "Hello",
"description": "返回问候语",
"inputSchema": {
"type": "object",
"required": ["name"],
"properties": {
"name": { "type": "string", "description": "问候语名称" }
}
},
"response": {
"type": "template",
"text": "Hello {{name}}!"
}
}
]
}
```
然后将其添加到 `mcp-plugins.json`：
```json
{
"source": "./plugins/my-json-plugin.json",
"enabled": true
}
```
### 安装插件
```bash
# 通过 CLI
node dist/cli.js add ./path/to/plugin
node dist/cli.js add some-npm-package
# 或直接编辑 mcp-plugins.json
```
## 代理配置
编辑 `mcp-proxy.json` 以添加远程 MCP 服务器：
```json
{
"targets": [
{
"name": "remote-server",
"url": "http://other-mcp:3000/mcp",
"enabled": true,
"description": "远程 MCP 服务器"
}
]
}
```
## 质量检查
```bash
npm test
npm run registry:validate
```
`registry:validate` 在您打开拉取请求之前检查 `mcp-registry.json` 和配置的 JSON 插件。
## 架构
参见 [架构说明](./docs/architecture.md) 和 [注册表架构](./docs/registry-schema.md) 获取贡献者设计细节。
参见 [Cursor 集成指南](./docs/cursor-integration.md) 配置此服务器以适用于单个项目或所有 Cursor 工作区。
参见 [技术路线图](./docs/roadmap.md) 获取计划的 v1.1、v1.2 和 v2.0 版本演进。
## 故障排除
- `http://localhost:3080/mcp` 返回 `Missing or invalid session ID`：直接在浏览器中打开 MCP 端点时会出现此情况。请使用 `http://localhost:3080` 处的控制面板，或通过 MCP 客户端连接。
- 控制面板更改未显示：更改 TypeScript、插件或配置文件后，请重新构建并重启服务器或容器。
- JSON 插件加载失败：运行 `npm run registry:validate` 获取无效 JSON 的确切字段路径。
- 沙箱升级失败：在控制面板中检查失败的检查及其 `Fix` 消息，然后重新运行沙箱验证。
## 项目结构
```text
aix-mcp-server/
├── src/
│ ├── index.ts # 入口（stdio / HTTP 传输）
│ ├── cli.ts # 插件管理 CLI
│ ├── loader.ts # 插件加载器
│ ├── plugin.ts # 插件接口
│ ├── proxy.ts # 代理转发
│ ├── registry.ts # 服务注册中心
│ ├── llm.ts # LLM 提供商集成
│ ├── plugins/ # 内置插件
│ │ ├── calculator.ts
│ │ ├── crypto.ts
│ │ ├── datetime.ts
│ │ ├── filesystem.ts
│ │ ├── system.ts
│ │ └── text-utils.ts
│ └── web/
│ ├── api.ts # 控制面板 API 路由
│ └── dashboard.html
├── mcp-plugins.json # 插件配置
├── mcp-proxy.json # 代理配置
├── mcp-registry.json # 服务注册中心数据
├── llm-config.json # LLM 提供商配置
├── docker-compose.yml
├── Dockerfile
└── package.json
```
## 许可证
MIT
