Perstack MCP 服务端与微代理框架

使用说明（Markdown格式）

• 项目简介

  • Perstack 是一个面向“微代理”的框架，旨在通过 MCP（Model Context Protocol）将资源、工具和提示等上下文能力标准化地暴露给大语言模型客户端。仓库中提供将 MCP 服务端以嵌入式方式运行的实现，以及与 MCP 客户端通信的适配层，方便将 MCP 服务端集成到应用中。

• 主要功能点

  • 托管与管理资源(Resources)：为 LLM 客户端提供数据访问能力和上下文资源。
  • 注册与执行工具(Tools)：定义工具并允许 LLM 调用外部功能。
  • 定义与渲染 Prompt 模板（Prompts）：支持基于 MCP 的上下文渲染与模板化交互。
  • JSON-RPC 通信：服务器端以标准的 JSON-RPC 形式处理请求与返回响应。
  • 多传输协议支持：支持在内存、STDIO、SSE 等传输方式下运行，方便嵌入式部署、调试和服务器对接。
  • 会话与能力声明：具备会话管理、能力声明和可扩展的工具/技能注册能力。
  • 资源与工具的动态管理：运行时可动态添加/移除技能、工具和委托关系，提升灵活性。

• 安装步骤

  • 该仓库提供的是一个综合框架，核心组件以 TypeScript 实现，需在 Node.js 环境中安装依赖并编译后使用。通常的使用方式是基于仓库中的构件/示例在本地或容器内部署运行。

• 服务器配置（MCP 客户端需要此信息建立连接）

  • MCP 客户端在连接 MCP 服务器时，需提供服务器启动信息，包括服务器名称、启动命令及参数，用以建立与服务器的通信通道。由于本仓库中的 MCP 服务器多以“嵌入式/内存模式”的实现存在（通过 InMemoryBaseSkillAdapter 等），实际启动并连接的逻辑多由运行时组件在进程内完成，以下描述仅作为连通性说明：
  • serverName（服务器标识，用于区分不同 MCP 服务端实例）
  • command（服务器启动命令）
  • args（服务器启动参数）
  • 说明：在本实现中，嵌入式服务器通过运行时组件直接暴露给 MCP 客户端，无需外部独立进程启动命令即可建立通信通道；若在外部进程中部署 MCP 服务，以上字段将用于定位与启动外部服务器。注：MCP 客户端不需要你在代码中硬编码服务器实现，它只需要知道服务器的名称、启动方式与参数的连接信息，以便建立传输通道并进行 JSON-RPC 通信。
  • 示例配置要点（为便于理解，仅作描述，不涉及代码实现）：
    • serverName: "perstack-base-mcp"
    • command: "node"（若外部进程部署）
    • args: ["dist/mcp-server.js", "--config", "perstack.toml"]
    • 注释：若使用嵌入式/内存模式，则不需要外部启动命令，运行时会在同一进程中建立 MCP 服务端与客户端的连接。

• 基本用法

  • 以嵌入式模式运行：在应用中通过 Perstack 提供的 SkillManager/Adapter 体系（如 InMemoryBaseSkillAdapter、McpSkillAdapter 等）将 MCP 服务端与 MCP 客户端绑定，使得 LLM 客户端能够通过 MCP 请求访问资源、调用工具与渲染提示。
  • 动态扩展：运行时可以添加/移除技能、委托他人 Expert、以及管理工具定义，提升系统对新任务的适配能力。
  • 调试与观测：通过运行时的事件流与日志，跟踪工具发现、连接时间、工具调用与结果等，便于诊断性能与功能问题。
  • 典型场景：将一个本地内存化的 MCP 服务端与一个 MCP 客户端配对，LLM 调用工具进行检索、计算或数据处理，并通过该 MCP 服务端提供的资源与提示实现上下文驱动的互动。

• 重要注意

  • MCP 服务核心在于标准化的接口和传输，仓库中的实现多为集成层/适配器实现，核心的 MCP 服务能力来自外部库（如 @modelcontextprotocol、@perstack/base 等），本工程则提供对这些能力的封装、编排和运行时集成。
  • 要理解完整的 MCP 服务端能力，需要查看 @perstack/base、@modelcontextprotocol 等依赖的实现细节，以及在运行时如何通过 InMemoryBaseSkillAdapter 将服务端能力“嵌入”到应用中。