NetADX AI-CORE-MCP API锅炉板

![TypeScript](https://www.typescriptlang.org) ![License: MIT](https://opensource.org/licenses/MIT) ![MCP SDK](https://github.com/modelcontextprotocol/typescript-sdk) ](https://nodejs.org) ![NetADX AI-CORE](https://netadx.ai) ![OpenAPI](https://spec.openapis.org/oas/v3.0.0) ![Swagger UI](http://localhost:8005/docs)

一个最小的、可生产的MCP（模型上下文协议）API服务器样板，用于构建可扩展的AI驱动的后端服务。

目的：简单、可扩展的基础，用于构建具有TypeScript、MongoDB和JWT身份验证的MCP-兼容API服务器。

建筑：简洁、最小的结构-易于理解，并可根据您的特定用例进行扩展。

概述

NetADX AI-CORE是一个简单、干净的样板，用于构建MCP API服务器。它提供：

MCP协议合规性 -官方SDK v1.0.0
TypeScript -类型安全开发
MongoDB集成 -数据库已准备好连接池
JWT身份验证 -安全的API访问
交互式API文档 -全面的Swagger/OpenAPI 3.0文档
直接执行TypeScript -无构建步骤 tsx
生产就绪 -日志记录、错误处理、优雅关机
最小和干净 -易于理解和扩展

包含什么

核心基础设施：

使用stdio和HTTP传输设置MCP服务器
MongoDB连接管理器
JWT身份验证管理器
温斯顿测井
环境配置
CRUD工具示例
交互式Swagger文档位于 /docs

部署：

快速部署脚本(deploy-quick.sh)
PM2生态系统配置
Docker支持
带CORS的Nginx反向代理
全面的部署文档

Claude桌面集成：

内置stdio包装器支持
地方发展与 development/mcp-stdio-wrapper
生产就绪的npm包 @netadx1ai/mcp-stdio-wrapper
完整的集成文档

特性

直接执行TypeScript

无需构建步骤！用途 tsx 直接运行TypeScript：

# Traditional approach (NOT used here)
npm run build        # Compile TS → JS
node dist/index.js   # Run compiled code

# NetADX AI-CORE approach
npx tsx src/index.ts  # Run TypeScript directly

优点：

更快的部署-无需编译步骤
更容易调试-错误指向实际 .ts 源文件
实时更新-更改代码、重新启动、准备就绪
更简单的CI/CD-只需直接同步TypeScript文件

技术栈

运行时：Node.js 18+
语言：TypeScript 5.2+（严格模式）
框架：MCP协议（官方SDK v1.0.0）
数据库：带连接池的MongoDB
运输：HTTP/HTTPS+stdio
认证：JWT（HS256）
日志记录：温斯顿
执行：tsx（直接执行TypeScript）

快速开始

先决条件

# Node.js 18+ required
node -v

# MongoDB (local or remote)
mongod --version

安装

# Clone or use this boilerplate
cd development/mcp_aicore_boilerplate

# Install dependencies
npm install

# Configure environment
cp .env.example .env
nano .env  # Edit with your settings

配置

编辑 .env 文件：

# Server
NODE_ENV=development
PORT=8005
USE_HTTP=true

# MongoDB
MONGODB_URI=mongodb://localhost:27017/netadx_aicore

# JWT
JWT_SECRET=your-secure-random-secret-here
JWT_EXPIRES_IN=24h

# Logging
LOG_LEVEL=info

跑

# Development mode
npm run dev

# Production mode (with tsx)
npm start

# Or directly
npx tsx src/index.ts

测试

# Health check
curl http://localhost:8005/health

# List tools (requires JWT token)
curl -H "x-access-token: YOUR_JWT_TOKEN" \
     http://localhost:8005/tools

# Call example tool
curl -X POST \
  -H "x-access-token: YOUR_JWT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"action":"list_items"}' \
  http://localhost:8005/tools/example_tool

交互式API文档

Swagger/OpenAPI 3.0文档

样板包括全面 交互式API文档 由Swagger UI和OpenAPI 3.0规范提供支持。

访问文档：

# Start the server
npm run dev

# Open documentation in browser
open http://localhost:8005/docs

特征：

🚀 交互式测试 -直接从浏览器测试所有端点
🔐 内置身份验证 -JWT和API密钥认证流程
📝 综合示例 -每个端点的真实请求/响应示例
✅ 架构验证 -针对OpenAPI模式的请求/响应验证
📊 错误文档 -完整的错误代码和恢复建议
⚡ 性能指标 -响应时间跟踪和优化提示

记录的关键终点：

GET /health -使用性能指标进行系统健康检查
GET /info -服务器信息和功能
GET /tools -列出所有可用的MCP工具
POST /tools/{name} -执行特定的MCP工具并进行验证
POST /rpc -用于MCP通信的JSON-RPC 2.0端点

身份验证方法：

JWT承载令牌: Authorization: Bearer
API密钥: X-API-Key:

快速测试示例：

# Test health endpoint (no auth required)
curl http://localhost:8005/health

# List tools (requires auth)
curl -H "Authorization: Bearer your-jwt-token" \
     http://localhost:8005/tools

# Execute example tool
curl -X POST \
  -H "Authorization: Bearer your-jwt-token" \
  -H "Content-Type: application/json" \
  -d '{"arguments": {"action": "list_items"}}' \
  http://localhost:8005/tools/example-tool

有关Swagger实现的详细文档，请参阅： MCP AI核心交换机文档

项目结构

mcp_aicore_boilerplate/
├── src/
│   ├── index.ts                 # Main entry point
│   ├── core/                    # MCP core infrastructure
│   │   ├── server.ts           # Base MCP server
│   │   └── index.ts
│   ├── tools/                   # MCP tools (your business logic)
│   │   └── example-tool.ts     # Example CRUD tool
│   ├── swagger/                 # API documentation
│   │   ├── index.ts            # Main Swagger/OpenAPI configuration
│   │   ├── tools.ts            # Tool-specific documentation
│   │   └── endpoints.ts        # Endpoint documentation
│   ├── transport/               # Transport layers
│   │   ├── http.ts             # HTTP transport with Swagger integration
│   │   ├── http-server.ts      # HTTP server wrapper
│   │   └── index.ts
│   ├── utils/                   # Utilities
│   │   ├── auth.ts             # JWT authentication
│   │   ├── config.ts           # Configuration management
│   │   ├── logger.ts           # Winston logging
│   │   ├── mongodb.ts          # MongoDB manager
│   │   └── index.ts
│   └── types/                   # TypeScript type definitions
│       └── index.ts
├── deployment/                  # Deployment configurations
│   ├── deploy.sh               # Full deployment script
│   ├── pm2/                    # PM2 configs
│   ├── docker/                 # Docker configs
│   ├── nginx/                  # Nginx reverse proxy with CORS
│   └── README.md
├── docs/                        # Documentation (cleaned)
├── .env.example                 # Environment template (simplified)
├── .env.deploy.example          # Deployment config template
├── deploy-quick.sh              # Quick TypeScript deployment
├── ecosystem.config.js          # PM2 config (uses tsx)
├── package.json                 # Dependencies
├── tsconfig.json                # TypeScript config
└── README.md                    # This file

配置

环境变量

中的所有配置 .env 文件：

# Server Configuration
NODE_ENV=development          # development | staging | production
PORT=8005                     # API server port
HOST=0.0.0.0                  # Listen address
USE_HTTP=true                 # true = HTTP, false = stdio

# MongoDB
MONGODB_URI=mongodb://localhost:27017/netadx_aicore
MONGODB_MAX_POOL_SIZE=50

# JWT Authentication
JWT_SECRET=change-this-secret
JWT_EXPIRES_IN=24h
JWT_ALGORITHM=HS256

# CORS
CORS_ORIGIN=http://localhost:3000
CORS_CREDENTIALS=true

# Logging
LOG_LEVEL=info               # error | warn | info | debug
LOG_FORMAT=json
LOG_FILE=/var/log/netadx-aicore/app.log

MongoDB集合

示例工具使用 example_items 收藏。根据需要添加自己的收藏。

发展

添加新工具

创建工具文件 在 src/tools/:

// src/tools/my-tool.ts
import { z } from 'zod';
import type { MongoDBManager } from '../utils/mongodb';
import type { Logger } from '../utils/logger';

const MyToolInputSchema = z.object({
  action: z.enum(['do_something']),
  data: z.string(),
});

export function createMyTool(mongodb: MongoDBManager, logger: Logger) {
  return {
    name: 'my_tool',
    description: 'My custom tool',
    inputSchema: {
      type: 'object',
      properties: {
        action: { type: 'string', enum: ['do_something'] },
        data: { type: 'string' },
      },
      required: ['action'],
    },
    async execute(input: unknown) {
      const { action, data } = MyToolInputSchema.parse(input);
      
      // Your logic here
      const result = { success: true, message: 'Done!' };
      
      return {
        content: [{ type: 'text', text: JSON.stringify(result, null, 2) }],
      };
    },
  };
}

注册工具 在 src/index.ts:

import { createMyTool } from './tools/my-tool';

// In registerTools() method:
const myTool = createMyTool(this.mongodb, this.logger);

// Add to tools list
this.server.setRequestHandler('tools/list', async () => {
  return {
    tools: [
      { name: exampleTool.name, description: exampleTool.description, inputSchema: exampleTool.inputSchema },
      { name: myTool.name, description: myTool.description, inputSchema: myTool.inputSchema },
    ],
  };
});

// Add to tools/call handler
if (name === myTool.name) {
  return await myTool.execute(args);
}

测试您的工具：

npx tsx src/index.ts

curl -X POST \
  -H "x-access-token: YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"action":"do_something","data":"test"}' \
  http://localhost:8005/tools/my_tool

运行测试

# Add tests in tests/ directory
npm test

代码质量

# Linting
npm run lint

# Format code
npm run format

# Type checking
npm run type-check

部署

快速部署（推荐）

用途 deploy-quick.sh 直接同步TypeScript文件：

# Configure deployment
cp .env.deploy.example .env.deploy
nano .env.deploy  # Set your server details

# Deploy all files
./deploy-quick.sh

# Deploy specific file
./deploy-quick.sh src/tools/my-tool.ts

# Deploy without restart
./deploy-quick.sh src/ true

PM2部署

# Start with PM2
pm2 start ecosystem.config.js --env production

# Monitor
pm2 status
pm2 logs netadx-aicore
pm2 monit

Docker部署

cd deployment/docker
docker build -t netadx-aicore .
docker run -d -p 8005:8005 --env-file .env netadx-aicore

Nginx反向代理

# Copy nginx config
sudo cp deployment/nginx/netadx-aicore-simple.conf /etc/nginx/sites-available/netadx-aicore

# Enable and reload
sudo ln -s /etc/nginx/sites-available/netadx-aicore /etc/nginx/sites-enabled/
sudo nginx -t
sudo systemctl reload nginx

看 deployment/README.md 和 deployment/nginx/README.md 获取完整指南。

Claude桌面集成

使用已发布的包（生产）

配置Claude Desktop以连接到已部署的API：

文件： ~/Library/Application Support/Claude/claude_desktop_config.json （macOS）

{
  "mcpServers": {
    "netadx-aicore": {
      "command": "npx",
      "args": ["-y", "@netadx1ai/mcp-stdio-wrapper@latest"],
      "env": {
        "API_URL": "https://your-api-domain.com",
        "JWT_TOKEN": "your-jwt-token-here",
        "LOG_FILE": "/tmp/netadx-aicore-mcp.log",
        "LOG_LEVEL": "info"
      }
    }
  }
}

使用本地开发包装器

对于本地开发和测试：

{
  "mcpServers": {
    "netadx-aicore-dev": {
      "command": "npx",
      "args": [
        "tsx",
        "/Volumes/T72/Work2025AI/mongodb/netadx-workspace/development/mcp-stdio-wrapper/src/index.ts"
      ],
      "env": {
        "API_URL": "http://localhost:8005",
        "JWT_TOKEN": "your-jwt-token-here",
        "LOG_FILE": "/tmp/netadx-aicore-dev-mcp.log",
        "LOG_LEVEL": "debug"
      }
    }
  }
}

看 Claude桌面集成指南以获取完整的文档。

API 文档

认证

所有API端点（除 /health)需要JWT身份验证：

# Include JWT token in header
curl -H "x-access-token: YOUR_JWT_TOKEN" http://localhost:8005/tools

端点

端点	方法	描述	文档
`/health`	GET	健康检查（无身份验证）	交互式文档
`/info`	GET	服务器信息（无身份验证）	交互式文档
`/tools`	GET	列出可用工具	交互式文档
`/tools/{tool_name}`	POST	执行特定工具	交互式文档
`/rpc`	POST	JSON-RPC 2.0端点	交互式文档
`/docs`	GET	Swagger文档	直接浏览器访问

工具操作示例

列出项目：

curl -X POST \
  -H "x-access-token: YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"action":"list_items"}' \
  http://localhost:8005/tools/example_tool

创建项目：

curl -X POST \
  -H "x-access-token: YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"action":"create_item","data":{"name":"Test","value":123}}' \
  http://localhost:8005/tools/example_tool

获取项目：

curl -X POST \
  -H "x-access-token: YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"action":"get_data","id":"item_id"}' \
  http://localhost:8005/tools/example_tool

贡献

这是一个样板模板。分叉并根据您的需求进行定制！

许可证

MIT许可证-NetADX AI-CORE团队

______________________________________________________________________

学习资源

支持

如有疑问或问题：

检查 deployment/README.md 获取部署帮助
检查 deployment/nginx/README.md 获取nginx/CORS帮助
查看中的示例工具 src/tools/example-tool.ts
看 Claude桌面集成用于MCP客户端设置

______________________________________________________________________

文档控制

创建时间：2025-10-31
版本：1.0.0
状态：锅炉板/模板
开发单位：NetADX AI-CORE团队
许可证：麻省理工学院

什么是NetADX AI-CORE？

NetADX AI-CORE是一款生产就绪的样板，用于构建符合MCP（模型上下文协议）的API服务器。它提供：

使用官方SDK v1.0.0完成MCP实现
经过生产测试的身份验证和授权
可扩展的MongoDB集成
全面的日志记录和错误处理
直接执行TypeScript（无构建步骤）
部署脚本和配置
干净、简约、易于扩展
Claude桌面集成支持

使用案例：

构建基于AI的后端API
创建符合MCP的服务
API快速原型设计
学习MCP协议实施

______________________________________________________________________

开始：

复制 .env.example 到 .env
配置MongoDB和JWT设置
跑 npm install && npm start
开始构建您的工具 src/tools/
使用stdio包装器与Claude Desktop集成

MCP aicore boilerplate

快速接入

详细介绍

NetADX AI-CORE-MCP API锅炉板

目录

概述

包含什么

特性

直接执行TypeScript

技术栈

快速开始

先决条件

安装

配置

跑

测试

交互式API文档

Swagger/OpenAPI 3.0文档

项目结构

配置

环境变量

MongoDB集合

发展

添加新工具

运行测试

代码质量

部署

快速部署（推荐）

PM2部署

Docker部署

Nginx反向代理

Claude桌面集成

使用已发布的包（生产）

使用本地开发包装器

API 文档

认证

端点

工具操作示例

贡献

许可证

学习资源

支持

目录标签

接入字段

权限和风险

来源信息

继续浏览同类 MCP