关键词

LLM后端工具集成AI应用框架上下文服务自动化API

项目简介

NextMCP 是一个基于 Model Context Protocol (MCP) 的 Python SDK，旨在简化 MCP 服务器的开发。它借鉴了 Next.js 的开发体验，提供了极简配置、强大的中间件和丰富的命令行工具，帮助开发者高效构建用于大型语言模型 (LLM) 应用的后端服务。您的 LLM 客户端可以通过标准化的 JSON-RPC 协议与 NextMCP 服务器通信，获取上下文信息、调用外部功能以及使用预定义的 Prompt 模板。

主要功能点

  • 完整的 MCP 支持：全面支持 MCP 协议定义的工具（Tools）、Prompt 模板（Prompts）和资源（Resources）。
  • 自动化发现：采用 Next.js 风格的基于文件结构的约定式配置，自动发现和注册您定义的工具、Prompt 和资源，无需手动注册。
  • 即时部署：提供一键部署到 Docker、Railway、Render、Fly.io 等平台的能力，并内置健康检查和优雅停机功能。
  • 丰富中间件：支持全局和特定功能的中间件，可轻松添加日志、认证、限流、缓存和输入验证等横切关注点。
  • 异步支持：全面支持 Python 的 'async/await' 模式，助力构建高并发、高性能的 I/O 密集型服务。
  • 身份认证与授权：内置 API Key、JWT、Session、OAuth 2.0（支持 GitHub/Google）以及细粒度 RBAC（角色/权限）控制。
  • WebSocket 传输：支持实时双向通信的 WebSocket 协议，适用于交互式 LLM 应用。
  • 插件系统：模块化、可重用的插件系统，方便扩展服务器功能。
  • 可观测性：内置 Prometheus 兼容的指标与监控系统，帮助您洞察服务器运行状态。

安装步骤

安装 NextMCP 非常简单，推荐使用 'pip'：

  1. 基础安装: 
    pip install nextmcp
  2. 推荐完整安装 (包含 CLI 和所有可选依赖): 
    pip install nextmcp[all]

服务器配置 (MCP客户端使用)

作为 MCP 客户端，您需要知道如何启动 NextMCP 服务器以便与之通信。通常，MCP 客户端会配置一个 JSON 格式的服务描述，其中包含启动服务器的命令。

以下是一个典型的 NextMCP 服务器启动配置示例，您需要根据实际的项目入口文件和端口进行调整。MCP 客户端只需要了解这些信息即可与服务器建立连接，无需了解代码细节：

{
  "server_name": "我的NextMCP服务器",
  "command": "python",
  "args": [
    "server.py",  // 替换为您的 NextMCP 项目的入口文件，例如 "app.py"
    "run",
    "--host",
    "0.0.0.0",    // 服务器监听的 IP 地址
    "--port",
    "8000"      // 服务器监听的端口号
  ],
  "description": "一个提供工具、Prompt 和资源服务的NextMCP后端。",
  "environment_variables": {
    "ENV_VAR_NAME": "value" // 可选：任何服务器运行所需的额外环境变量
  }
}
  • 'server_name': 您服务器的友好名称，方便识别。
  • 'command': 启动 Python 脚本的解释器，通常是 'python'。
  • 'args': 启动服务器所需的命令行参数列表。
    • 'server.py': 您的 NextMCP 项目的入口文件（例如，'server.py' 或 'main.py'）。
    • 'run': NextMCP CLI 运行服务器的子命令。
    • '--host 0.0.0.0': 服务器监听的 IP 地址，'0.0.0.0' 表示监听所有可用网络接口。
    • '--port 8000': 服务器监听的端口号。
  • 'description': 服务器的简要描述。
  • 'environment_variables': (可选) 任何服务器运行所需的额外环境变量。

请注意：如果您的 NextMCP 服务器配置了 WebSocket 传输，您可能需要将 'args' 调整为 '["server.py", "run", "--transport", "websocket", "--host", "0.0.0.0", "--port", "8765"]' 并关注其 WebSocket 端口（例如 '8765'）。具体请参考服务器端的配置。

基本使用方法

1. 创建项目结构 (推荐使用约定式方法)

NextMCP 推荐使用类似于 Next.js 的约定式文件结构，方便自动发现：

my-mcp-server/
├── nextmcp.config.yaml  # 项目配置文件
├── server.py            # 服务器入口文件
├── tools/               # 存放您的工具定义
│   ├── __init__.py
│   └── posts.py         # 示例：博客文章管理工具
├── prompts/             # 存放您的 Prompt 模板定义
│   ├── __init__.py
│   └── workflows.py     # 示例：工作流 Prompt
└── resources/           # 存放您的上下文资源定义
    ├── __init__.py
    └── blog_resources.py # 示例：博客数据资源

2. 定义工具 (Tools)

在 'tools/posts.py' 中定义一个工具，例如创建博客文章：

# tools/posts.py
from nextmcp import NextMCP

app = NextMCP.from_config() # 从配置文件加载应用

@app.tool()
def create_post(title: str, content: str) -> dict:
    """创建一个新的博客文章"""
    # 这里实现创建文章的业务逻辑，例如写入数据库
    print(f"创建文章: {title}")
    return {"id": 1, "title": title, "content": content, "status": "created"}

@app.tool()
def list_posts() -> list:
    """列出所有博客文章"""
    return [{"id": 1, "title": "欢迎使用 NextMCP"}, {"id": 2, "title": "我的第二篇文章"}]

3. 定义 Prompt 模板 (Prompts)

在 'prompts/workflows.py' 中定义一个 Prompt 模板，例如规划度假：

# prompts/workflows.py
from nextmcp import NextMCP, argument

app = NextMCP.from_config()

@app.prompt(description="计划一次完整的度假行程")
@argument("destination", description="您希望前往的目的地", suggestions=["巴黎", "东京", "纽约"])
@argument("budget", type="integer", description="您的旅行预算金额（美元）")
def vacation_planner(destination: str, budget: int) -> str:
    """
    根据目的地和预算，为您生成一份详细的度假行程计划。
    AI 可以调用以下工具来辅助规划：
    - flight_search: 查找最佳航班
    - hotel_search: 查找合适的酒店住宿
    并参考以下资源获取上下文信息：
    - resource://user/preferences: 获取您的个人旅行偏好设置
    """
    return f"请为我规划一次前往 {destination} 的度假行程，总预算为 ${budget}。请确保行程经济实惠且充满乐趣。"

4. 定义资源 (Resources)

在 'resources/blog_resources.py' 中定义一个资源，例如博客统计数据：

# resources/blog_resources.py
from nextmcp import NextMCP

app = NextMCP.from_config()

@app.resource("blog://stats", mime_type="application/json", description="博客实时统计数据")
def blog_stats() -> dict:
    """提供博客文章的浏览量、评论数、活跃用户数等实时统计数据。"""
    return {"total_posts": 105, "total_views": 12345, "active_users": 68, "last_updated": "2024-07-30"}

@app.resource_template("blog://posts/{post_id}", description="按 ID 获取单篇博客文章")
def get_post_by_id(post_id: int) -> dict:
    """根据文章 ID 获取文章的详细内容。"""
    # 模拟从数据库获取文章
    if post_id == 1:
        return {"id": 1, "title": "欢迎使用 NextMCP", "author": "管理员", "content": "这是我们的第一篇博客文章..."}
    return {"error": "文章未找到"}

5. 编写服务器入口

在 'server.py' 中，使用 'NextMCP.from_config()' 自动加载您的定义：

# server.py
from nextmcp import NextMCP

# NextMCP 会根据 nextmcp.config.yaml 或默认约定，
# 自动在 'tools/', 'prompts/', 'resources/' 目录下发现并注册您的定义。
app = NextMCP.from_config()

if __name__ == "__main__":
    print("NextMCP 服务器正在启动...")
    app.run(host="0.0.0.0", port=8000) # 启动服务器，默认使用 HTTP (Stdio) 传输协议
    print("NextMCP 服务器已停止。")

6. 运行您的服务器

在项目根目录（'my-mcp-server/'）下打开终端，执行：

python server.py

或者使用 NextMCP 的命令行工具 (CLI)：

mcp run server.py --host 0.0.0.0 --port 8000

服务器启动后，您的 MCP 客户端就可以通过 JSON-RPC 协议连接 'http://0.0.0.0:8000' (如果配置了 WebSocket 传输，则连接 'ws://0.0.0.0:<websocket_port>') 来发现和调用您的工具、Prompt 和资源了。

信息

分类

开发者工具

访问项目