AI导哈

模型上下文协议查询服务

一个基于Express.js和Next.js的生产就绪实现，展示LLM代理如何通过标准化协议与外部工具交互。

  • by putupadang
  • JavaScript
  • 本地部署
  • 更新于
在 GitHub 查看 putupadang/mcp-chat-query

使用说明

🚀 MCP聊天查询-模型上下文协议演示

生产就绪的实施 模型上下文协议（MCP） 配备Express.js服务器和Next.js前端。该项目演示了LLM代理如何通过标准化协议与外部工具进行交互。

📺 演示

  • 现场演示：[您的Vercel网址]
  • API文档：[您的服务器URL]/api文档
  • 演示视频：[您的YouTube/Drive链接]

✨ 特性

MCP服务器（Express.js）

  • 工具注册表：使用JSON模式验证的动态工具注册
  • OpenAPI规范：交互式Swagger UI文档
  • 认证：带有RBAC的基于API密钥的身份验证（基于角色的访问控制）
  • 速率限制：可配置的请求限制
  • 审计日志：完成工具调用跟踪
  • 结构化日志记录：使用Pino进行生产准备测井
  • 数据库：Prisma ORM+MongoDB（默认为本地）
  • 综合测试：单元和集成测试，覆盖率超过70%
  • Docker支持：生产就绪的集装箱化

前端（Next.js）

  • 交互式聊天界面：美观、反应灵敏的聊天界面
  • 工具可视化：实时显示工具调用和结果
  • 现代设计：Tailwind CSS+shadcn/ui组件
  • 类型安全：完全支持TypeScript
  • 服务器端API路由：安全的API密钥管理

开发运维

  • Docker Compose：多容器编排
  • GitHub 操作：自动化CI/CD管道
  • 容器注册表：自动构建Docker镜像
  • 健康检查：服务监控和自动重启

🏗️ 建筑

┌─────────────────┐         ┌─────────────────┐         ┌─────────────────┐
│   Next.js App   │────────▶│  MCP Server     │────────▶│  Tool Handlers  │
│  (Frontend UI)  │  HTTP   │  (Express.js)   │         │  (Business Logic)│
└─────────────────┘         └─────────────────┘         └─────────────────┘
        │                            │                           │
        │                            ▼                           ▼
        │                    ┌──────────────┐          ┌────────────────┐
        │                    │   Validator  │          │   MongoDB       │
        │                    │  (AJV+Schema)│          │   (Prisma)      │
        └───────────────────▶└──────────────┘          └────────────────┘
               API Routes            │
                                     ▼
                             ┌──────────────┐
                             │  Audit Log   │
                             │  (Memory)    │
                             └──────────────┘

🚀 快速开始

先决条件

  • Node.js 18+
  • npm或纱线
  • Docker和Docker Compose（可选）
  • MongoDB 6+（本地）或Docker（用于数据库）

选项1：本地运行

  1. 克隆仓库
git clone https://github.com/YOUR_USERNAME/mcp-portfolio.git
cd mcp-portfolio
  1. 启动MCP服务器
cd server
npm install
cp .env.example .env
# Edit .env with your API key (APP_API_KEY)
# Ensure MongoDB is running locally:
#   - Docker:        docker compose up -d mongo
#   - Homebrew (mac): brew services start mongodb-community

# Initialize database (Prisma + MongoDB)
npm run prisma:generate
npm run prisma:push
npm run prisma:seed

# Start development server
npm run dev
# Server running on http://localhost:4000
  1. 启动Next.js应用程序 （在新航站楼）
cd app
npm install
cp .env.local.example .env.local
# Edit .env.local with server URL and API key
npm run dev
# App running on http://localhost:3000
  1. 访问应用程序
  • 前端：http://localhost:3000
  • API文件：http://localhost:4000/api-docs
  • 健康：http://localhost:4000/admin/health

选项2：使用Docker运行

docker compose中包含MongoDB服务；无需安装本地MongoDB。

# Set API key
export APP_API_KEY=your-secret-key

# Start all services
docker-compose up -d

# View logs
docker-compose logs -f

# Stop services
docker-compose down

📚 API文档

可用工具

1. search_db -搜索产品数据库（MongoDB+Prisma）

{
  "tool": "search_db",
  "input": {
    "q": "laptop",
    "category": "Electronics",
    "limit": 5
  }
}

2. 创建_票 -创建支持票（MongoDB）

{
  "tool": "create_ticket",
  "input": {
    "title": "Login Issue",
    "body": "Cannot login to my account",
    "priority": "high"
  }
}

3. run_query -执行数据库查询（仅限管理员，模拟）

{
  "tool": "run_query",
  "input": {
    "query": "SELECT * FROM products LIMIT 5"
  }
}

核心终点

方法 端点 描述 需要身份验证
得到 /tools 列出所有可用工具 ✅
职位 /invoke 调用特定工具 ✅
职位 /agent/ask 向代理发送消息 ✅
得到 /admin/health 健康检查 ✅
得到 /admin/audit 获取审核日志 ✅
得到 /api-docs Swagger用户界面 ❌

认证

所有受保护的终结点都需要标头中的API密钥：

curl -H "x-api-key: your-api-key" http://localhost:4000/tools

🧪 测试

运行服务器测试

cd server
npm test              # Run all tests
npm run test:watch    # Watch mode
npm run test:coverage # With coverage

测试覆盖率

当前覆盖范围： 70%+ （分支、函数、行、语句）

🔒 安全特性

  • API密钥验证：安全的端点访问
  • 基于角色的访问控制：基于角色的工具权限（管理员、用户）
  • 速率限制：防止滥用（默认100个要求/分钟）
  • 输入验证：使用AJV进行JSON模式验证
  • 审计日志：跟踪所有工具调用
  • Helmet.js：安全标题
  • 跨域资源共享：可配置的来源白名单
  • 危险操作检测：防止破坏性查询

📊 演出

  • 工具执行：平均约100-200ms
  • 速率限制：100个请求/分钟（可配置）
  • 内存使用：每次服务约50MB
  • 并发请求：处理100+并发

🛠️ 技术栈

后端

  • Express.js -Web框架
  • 阿联酋 -JSON模式验证器
  • 皮诺 -结构化日志记录
  • Swagger用户界面 -API文件
  • 棱镜 -用于MongoDB的ORM/客户端
  • MongoDB -文档数据库
  • 测试 -测试框架

前端

  • Next.js 14 -React框架
  • TypeScript -类型安全
  • 尾风CSS -造型
  • Lucide图标 -图标库

开发运维

  • 码头工人 -集装箱化
  • GitHub 操作 -CI/CD
  • Docker Compose -编排

📁 项目结构

mcp-portfolio/
├── server/                 # Express.js MCP server
│   ├── src/
│   │   ├── config/        # Configuration
│   │   ├── middleware/    # Auth, audit, permissions
│   │   ├── routes/        # API routes
│   │   ├── tools/         # Tool registry & handlers
│   │   ├── validators/    # Schema validators
│   │   ├── db/            # Prisma client
│   │   └── index.js       # Entry point
│   ├── prisma/            # Prisma schema & seed
│   ├── __tests__/         # Test suites
│   ├── Dockerfile
│   └── package.json
│
├── app/                    # Next.js frontend
│   ├── app/
│   │   ├── api/chat/      # API routes
│   │   ├── globals.css    # Global styles
│   │   ├── layout.tsx     # Root layout
│   │   └── page.tsx       # Home page
│   ├── components/        # React components
│   ├── lib/               # Utilities
│   ├── Dockerfile
│   └── package.json
│
├── .github/
│   ├── workflows/         # CI/CD pipelines
│   └── ISSUE_TEMPLATE/    # Issue templates
│
├── docs/                   # Documentation
├── docker-compose.yml
├── LICENSE
└── README.md

🎯 路线图

  • []添加真正的LLM集成（OpenAI/Anthropic）
  • []实现RAG的矢量存储
  • []添加多步骤工具链
  • []实现工具结果缓存
  • []添加Kubernetes清单
  • []创建性能基准
  • []使用Playwright添加E2E测试
  • []实现WebSocket以实现实时更新
  • []添加更多工具示例（电子邮件、日历等）
  • []创建全面的视频教程

🤝 贡献

欢迎投稿！请查看我们的 贡献指南.

  1. 复刻仓库
  2. 创建功能分支(git checkout -b feature/AmazingFeature)
  3. 提交您的更改(git commit -m 'feat: add amazing feature')
  4. 推到分支(git push origin feature/AmazingFeature)
  5. 打开拉取请求

📄 许可证

此项目根据MIT许可证获得许可-请参阅 许可证 文件以获取详细信息。

🙏 致谢

  • 受模型上下文协议规范的启发
  • 采用现代最佳实践构建
  • 社区反馈和贡献

📧 联系

你的名字- @你的推特

项目链接： https://github.com/YOUR_USERNAME/mcp-portfolio

⭐ 标记此回购 如果你觉得有帮助的话！

内置于❤️ [你的名字]

相关 MCP