Spectral MCP 服务器实现

关键词

API 调用JSON-RPC服务端实现工具执行OpenAPI 集成

使用说明

  • 项目简介

    • Spectral 仓库实现了一个用于 MCP（Model Context Protocol） 的服务器端框架。核心功能包括注册和执行“工具”（Tools）、管理“资源/上下文”数据，以及提供与 LLM 客户端的交互能力。服务器通过 JSON-RPC 进行标准化通信，支持多种传输方式（此实现以 STDIO 为主的 MCP 服务）。
    • 服务器设计目标是把应用后台能力（如对外 API 调用、数据读取等）以可控、可扩展的方式暴露给 LLM 客户端，便于在对话中动态调用外部功能、读取资源、以及渲染/输出提示信息等。

  • 主要功能点

    • MCP 工具注册与暴露
      • 通过应用存储中的工具定义，将每个工具暴露为 MCP Tool，供客户端发现和调用。
      • 支持按应用注册多工具，并形成名称命名空间如 app_tool。
    • 工具执行与输入校验
      • 客户端发起工具调用后，服务器解析参数、执行请求构造、并通过外部 HTTP 请求完成调用，返回执行结果文本。
      • 支持输入参数校验、默认参数注入，以及对缺失参数的友好处理。
    • 资源与上下文的处理
      • 服务器侧集成对资源、上下文等信息的管理，便于 LLM 在分析与生成工具时参考上下文。
    • HTTP 请求与外部 API 调用
      • 针对工具定义的请求模板，服务器能够按 base_url、路径、查询、头部、请求体等要素构造请求并执行，返回响应内容。
    • 安全与认证
      • 支持对需要认证的工具进行 Token/Header 传递，自动从本地存储读取并附加到请求中，必要时触发重认证流程。
    • JSON-RPC 传输与多端接入
      • MCP 服务器实现了标准的 JSON-RPC 请求/响应格式，便于 LLM 客户端以一致的协议对工具、资源进行操作。
    • Server 启动与传输
      • 通过 STDIO 启动 MCP 服务（spectral mcp stdio），实现与 LLM 客户端的直接、低延迟通信。

  • 安装与运行步骤

    • 克隆源码并安装依赖
      • 需要 Python 3.11 及以上环境，安装所需依赖包（如 pydantic、mcp、requests 等）。
    • 启动 MCP 服务器
      • 指令：spectral mcp stdio
      • 该命令会启动一个基于 STDIO 的 MCP 服务器，监听来自 LLM 客户端的 JSON-RPC 请求。
    • 数据准备
      • 通过 Spectral 的数据存储（应用、工具、以及凭证等信息）配置工具、资源和认证信息，以便服务器在运行时能够正确注册工具并执行请求。
    • 客户端配置
      • MCP 客户端需要按照服务器启动命令与参数来连接，具体为服务器名称、启动命令、以及必要参数（见下方“服务器配置”示例）。

  • 服务器配置（MCP 客户端所需的连接信息，不包含客户端实现细节）

    • 服务器名称：spectral
    • 启动命令：spectral
    • 启动参数（args）：["mcp", "stdio"]
    • 说明：该配置用于 MCP 客户端通过标准输入输出与服务器建立通信。服务器在启动后会接收 JSON-RPC 请求并返回相应结果。以上配置来自仓库实现中对 MSP 服务的启动路径与命令约定。

  • 基本使用方法

    • 服务器端
      • 启动后，服务器将准备好接受来自 MCP 客户端的工具列表、调用请求，以及可能的资源读取等操作请求。
    • 客户端（示例用法，实际客户端实现可能不同）
      • 通过配置文件提供 server_name、command 与 args，启动 MCP 客户端进程并通过其输出/输入通道向服务器发起请求。
      • 常见的请求类型包括：列出工具（ListTools）、调用工具（CallTool）、以及获取/渲染提示模板等。
    • 常见工作流程
        1. 客户端连接并请求注册工具清单。
        1. 客户端选择某个工具并传入所需参数。
        1. 服务器执行并返回结果文本，可能包含结构化数据。
        1. 根据返回数据，LLM 可以继续进行推理、调用其他工具或渲染新的提示。
    • 运行与调试建议
      • 确保存储中有应用、工具与相应的授权信息（如 token）。
      • 若遇到认证相关错误，按照提示进行登录或更新 token。
      • 使用日志或调试模式观察 LLM 与 MCP 服务器之间的交互流程，便于定位参数传递或响应格式问题。

  • 备注

    • 将工具定义、授权、以及其他资源均以标准化、可验证的形式暴露给 LLM 客户端，确保每次调用的输入输出都可重复、可追踪。
    • 该实现包含对工具、请求、响应、以及资源的完整函数与数据结构定义，并包含对应的单元测试，确保 MCP 服务器端的核心逻辑完整、可运行。

  • 关键词

    • 后端服务、JSON-RPC、工具执行、外部 API 调用、会话管理

  • 分类

    • 5

服务器信息

访问项目