AI导哈

聊天应用

一个全栈聊天应用，使用FastMCP实现MCP协议，支持实时通信和工具调用。

  • by Tattzy25
  • TypeScript
  • 本地部署
  • 更新于
在 GitHub 查看 Tattzy25/mcp-chat

使用说明

MCP聊天

一个使用FastMCP实现正确MCP（模型上下文协议）的全栈聊天应用程序。

特性

  • ✅ 真实MCP服务器 -使用HTTP传输实现FastMCP
  • ✅ 合适的工具系统 -具有JSON模式的类型安全MCP工具
  • ✅ 没有沉默的退路 -全程显式错误处理
  • ✅ Next.js前端 -现代基于React的用户界面
  • ✅ Vercel API路线 -无服务器后端集成

快速开始

先决条件

  • Python 3.10+（推荐使用Python 3.12）
  • Node.js 18+与npm
  • Git

安装

  1. 克隆仓库

    git clone https://github.com/Tattzy25/mcp-chat.git
cd mcp-chat

  2. 安装Python依赖项

    pip install -r requirements.txt

  3. 安装Node.js依赖项

    cd TaTTTy/tattty
npm install
cd ../..

运行应用程序

选项1：一起运行一切（建议用于开发）

./start.sh

这将：

  • 在端口8000上启动FastMCP服务器
  • 在端口3000上启动Next.js开发服务器
  • 按Ctrl+C时处理优雅关机

选项2：单独运行服务器

终端1-MCP服务器：

./start-mcp.sh
# or manually:
python3 server.py

终端2-Next.js前端：

cd TaTTTy/tattty
npm run dev

选项3：仅测试MCP服务器

# Test the server with the included client
python3 client.py

访问应用程序

  • 前端: http://localhost:3000
  • MCP服务器: http://localhost:8000/mcp

建筑

MCP服务器(server.py)

FastMCP服务器提供MCP协议实现：

  • 运输：端口8000上的HTTP
  • 路径: /mcp
  • 可用工具:
    • add(a: int, b: int) -加两个数字
    • search_web(query: str) -网络搜索功能
    • get_weather(location: str) -天气信息
  • 资源:
    • config://version -服务器版本
    • config://info -服务器信息

MCP客户端(client.py)

测试客户端，演示：

  • 连接到MCP服务器
  • 列出可用工具
  • 使用参数调用工具
  • 阅读资源
  • 正确的错误处理

API大桥(api/mcp.js)

Vercel无服务器功能：

  • 接受HTTP POST请求
  • 通过Python CLI包装器调用MCP服务器
  • 返回结构化JSON响应
  • 提供响亮的错误消息（没有无声的回退）

Python CLI包装器(mcp_call.py)

Node.js和Python的桥梁：

  • 用于调用MCP工具的CLI界面
  • JSON输入/输出
  • 正确的错误传播

API使用

调用工具

curl -X POST http://localhost:3000/api/mcp \
  -H "Content-Type: application/json" \
  -d '{"tool": "add", "args": {"a": 10, "b": 20}}'

答复：

{
  "text": "30",
  "data": 30,
  "content": [{"type": "text", "text": "30"}],
  "tool": "add",
  "success": true
}

发送消息（使用search_web工具）

curl -X POST http://localhost:3000/api/mcp \
  -H "Content-Type: application/json" \
  -d '{"message": "Python MCP protocol"}'

添加新工具

  1. 编辑 server.py
  2. 添加新功能 @mcp.tool 装饰器
  3. 包括类型提示和docstring
  4. 重新启动服务器

例子：

@mcp.tool
def multiply(x: float, y: float) -> float:
    """Multiply two numbers.
    
    Args:
        x: First number
        y: Second number
        
    Returns:
        The product of x and y
    """
    return x * y

该工具将自动：

  • 从类型提示生成JSON模式
  • 验证输入参数
  • 返回结构正确的响应

错误处理

此实施遵循 “仅限大声错误” 哲学：

  • ❌ 没有无声的倒退
  • ✅ 显式错误消息
  • ✅ 正确的HTTP状态代码
  • ✅ 详细的错误上下文

错误响应示例

{
  "error": "MCP Connection Error",
  "message": "Connection refused",
  "details": "Failed to connect to MCP server. Ensure the FastMCP server is running on port 8000."
}

测试

测试MCP服务器

python3 client.py

测试API终结点

python3 mcp_call.py add '{"a": 5, "b": 3}'

通过HTTP进行测试

curl -X POST http://localhost:3000/api/mcp \
  -H "Content-Type: application/json" \
  -d '{"tool": "add", "args": {"a": 7, "b": 5}}'

故障排除

MCP服务器无法启动

  • 检查端口8000是否正在使用中： lsof -i :8000
  • 验证Python安装： python3 --version
  • 确保安装了fastmcp： pip list | grep fastmcp

客户端无法连接

  • 验证服务器是否正在运行： curl http://localhost:8000/mcp 2>&1 | head
  • 检查防火墙设置
  • 在服务器输出中查找错误消息

API调用失败

  • 确保MCP服务器首先运行
  • 检查终端中的API日志
  • 测试用 python3 mcp_call.py 直接
  • 验证Python是否可以从Node.js访问

文档

项目结构

mcp-chat/
├── server.py              # FastMCP server implementation
├── client.py              # MCP test client
├── mcp_call.py           # Python CLI wrapper for tools
├── requirements.txt       # Python dependencies
├── start.sh              # Start both servers
├── start-mcp.sh          # Start MCP server only
├── api/
│   └── mcp.js            # Vercel API route
├── TaTTTy/tattty/        # Next.js frontend
│   ├── app/
│   ├── components/
│   └── lib/
└── public/               # Static assets

环境变量

中的可选配置 .env.local:

# MCP Server URL (defaults to http://localhost:8000/mcp)
MCP_SERVER_URL=http://localhost:8000/mcp

# MCP server host (defaults to 0.0.0.0)
MCP_HOST=0.0.0.0

# MCP server port (defaults to 8000)
MCP_PORT=8000

部署

MCP服务器

对于生产部署：

  1. 使用流程管理器（PM2、systemd、主管）
  2. 配置反向代理（nginx、Apache）
  3. 设置SSL/TLS证书
  4. 使用环境变量进行配置

systemd示例：

[Unit]
Description=MCP FastMCP Server
After=network.target

[Service]
Type=simple
User=www-data
WorkingDirectory=/path/to/mcp-chat
ExecStart=/usr/bin/python3 server.py
Restart=always

[Install]
WantedBy=multi-user.target

Next.js前端

部署到Vercel：

cd TaTTTy/tattty
vercel

或者使用Docker、传统托管等。

贡献

  1. 分叉存储库
  2. 创建要素分支
  3. 进行更改
  4. 如果适用，添加测试
  5. 提交拉取请求

许可证

[在此处添加您的许可证]

支持

鸣谢

相关 MCP