ARTICLE DETAIL

资讯详情

深耕网站视觉设计与运营推广的一线实战洞察。

PraisonAI MCP 服务器实战指南:通过 MCP 协议把 Agent 能力接入 Claude Desktop、Cursor 与任意 MCP 客户端

PraisonAI MCP 服务器实战指南:通过 MCP 协议把 Agent 能力接入 Claude Desktop、Cursor 与任意 MCP 客户端 PraisonAI MCP 服务器实战指南通过 MCP 协议把 Agent 能力接入 Claude Desktop、Cursor 与任意 MCP 客户端【免费下载链接】PraisonAIPraisonAI — Hire a 24/7 AI Workforce. Stop writing boilerplate and start shipping autonomous self-improving agents that research, plan, code, and execute tasks. Deployed in 5 lines of code with built-in memory, RAG, and support for 100 LLMs.项目地址: https://gitcode.com/GitHub_Trending/pr/PraisonAIPraisonAI 内置了完整的 MCPModel Context Protocol服务器实现可以将 Agent、工作流、记忆、知识库、图像生成与语音转写等能力以标准 MCP 工具Tools、资源Resources和提示词Prompts的形式暴露给任何 MCP 兼容客户端。本指南以 examples/mcp_server/README.md 为主线结合仓库源码server.py、cli.py、registry.py与可运行的示例脚本带你完成从启动 STDIO / HTTP Stream 服务器、注册自定义工具、编写客户端到配置 Claude Desktop / Cursor 的完整闭环。读完本文你将掌握praisonai mcp全系列 CLI 命令并能在 5 分钟内把 PraisonAI 的能力接入主流 AI 编辑器。MCP 与 PraisonAI把 Agent 能力标准化MCP 是 AI 应用与工具之间的开放协议采用 JSON-RPC 2.0 消息格式。PraisonAI 将其 Agent 运行时能力封装成 MCP 服务器客户端只需遵循协议即可调用工具Tools如praisonai.chat.completion、praisonai.agent.run、praisonai.workflow.run等可执行操作资源Resources如praisonai://memory/sessions、praisonai://mcp/status等可读取的状态与数据 URI提示词Prompts如deep-research、code-review等可复用的提示模板。支持的客户端包括 Claude Desktop、Cursor、Windsurf、VSCode MCP 客户端以及任何 MCP 兼容客户端。从源码看MCP 服务器实际实现在praisonai-mcp子包中src/praisonai/praisonai/mcp_server/__init__.py仅作为兼容层shim通过ensure_praisonai_mcp()引导后把praisonai.mcp_server别名到praisonai_mcp.mcp_server。协议版本与传输方式这些示例使用 MCP 协议版本2025-11-25。在 server.py 中可以看到PROTOCOL_VERSION 2025-11-25 SUPPORTED_VERSIONS [2025-11-25, 2025-03-26, 2024-11-05]服务器同时兼容 2025-03-26 与 2024-11-05 两个旧版本客户端在initialize握手时声明协议版本服务器返回协商结果。PraisonAI MCP 服务器支持两种传输方式传输方式适用场景典型客户端stdio本地进程间通信随客户端进程启动Claude Desktop、Cursorhttp-stream网络访问可独立部署并跨进程共享Web 应用、远程客户端、多客户端共享四种开箱即用的示例脚本examples/mcp_server 目录下提供了 4 个核心示例另有mcp_auth_example.py、mcp_elicitation_example.py、mcp_sampling_example.py、mcp_tasks_example.py等进阶示例。1. STDIO 服务器stdio_server.pySTDIO 传输通过标准输入输出与客户端通信是 Claude Desktop 集成的推荐方式。直接运行python stdio_server.py或通过 CLI 等价启动praisonai mcp serve --transport stdio其核心逻辑非常简洁stdio_server.pyfrom praisonai.mcp_server.server import MCPServer from praisonai.mcp_server.adapters import register_all register_all() # 注册全部工具、资源与提示词 server MCPServer( namepraisonai, version1.0.0, instructionsPraisonAI MCP Server - AI agent capabilities via MCP protocol., ) server.run(transportstdio)2. HTTP Stream 服务器http_stream_server.pyHTTP Stream 传输适合基于 Web 的集成服务器默认监听127.0.0.1:8080端点路径为/mcppython http_stream_server.pyCLI 等价命令praisonai mcp serve --transport http-stream --port 8080启动后访问http://127.0.0.1:8080/mcp脚本会打印协议版本并等待CtrlC停止。HTTP Stream 模式下每个客户端通过MCP-Session-Id响应头获得会话标识后续所有 JSON-RPC 请求都需携带该会话 ID。3. 自定义工具服务器custom_tools_server.pyMCP 服务器不只是暴露内置能力还支持通过装饰器register_tool注册你自己的 Python 函数并立即暴露为 MCP 工具custom_tools_server.pyfrom praisonai.mcp_server.server import MCPServer from praisonai.mcp_server.registry import register_tool, get_tool_registry register_tool(custom.greet) def greet(name: str) - str: Greet a person by name. return fHello, {name}! Welcome to PraisonAI. register_tool(custom.calculate) def calculate(expression: str) - str: Safely evaluate a mathematical expression. # 基于 AST 的安全表达式求值仅允许白名单运算符 ... # 查看已注册的工具 registry get_tool_registry() for tool in registry.list_all(): print(f - {tool.name}: {tool.description}) server MCPServer(namepraisonai-custom, version1.0.0) server.run(transporthttp-stream, host127.0.0.1, port8080)从 registry.py 的register_tool实现可以看到它既可作为装饰器register_tool(name)也可直接调用register_tool(name, handler)。注册时若未显式提供description和input_schema会自动从函数的 docstring 与签名推断生成即函数即工具。register_resource与register_prompt采用同样的注册模式分别用于暴露自定义资源 URI 与提示词模板。4. 客户端示例mcp_client_example.py先启动服务器praisonai mcp serve --transport http-stream --port 8080再运行客户端python mcp_client_example.py该客户端mcp_client_example.py完整演示了一次 MCP 会话的标准握手与调用流程initialize发送协议版本2025-11-25与clientInfo从响应头获取MCP-Session-Idnotifications/initialized通知服务器初始化完成tools/list列出可用工具默认打印前 5 个resources/list列出可用资源 URIprompts/list列出可用提示词resources/read读取praisonai://mcp/status获取服务器状态prompts/get获取deep-research提示词模板传入topic、depth参数ping验证连接存活。每一步都对应服务器端 server.py 中注册的 JSON-RPC 方法处理器initialize、ping、tools/list、tools/call、tools/search、resources/list、resources/read、prompts/list、prompts/get、logging/setLevel。praisonai mcp CLI 命令全解析praisonai mcp子命令由 cli.py 中的MCPServerCLI实现常用命令如下# 启动 STDIO 服务器默认传输方式 praisonai mcp serve --transport stdio # 启动 HTTP Stream 服务器指定端口 praisonai mcp serve --transport http-stream --port 8080 # 带 API Key 认证启动 praisonai mcp serve --transport http-stream --api-key YOUR_KEY # 列出可用工具 / 资源 / 提示词 praisonai mcp list-tools praisonai mcp list-resources praisonai mcp list-prompts # 生成指定客户端的接入配置 praisonai mcp config-generate --client claude-desktop # 检查服务器健康状态 praisonai mcp doctor从 cli.py 可以看到完整命令路由除上述命令外还支持serve-recipe、list-recipes、validate-recipe、inspect-recipe、config-generate-recipe、auth、tasks、tools等子命令。serve 命令的扩展选项serve命令支持丰富选项源码见 cli.py选项说明默认值--transport传输方式stdio或http-streamstdio--hostHTTP 监听地址127.0.0.1--portHTTP 端口8080--endpointHTTP 端点路径/mcp--api-key单一通配符作用域 API Key无--keys-file按 Key 分配作用域的 JSON 文件最小权限无--name服务器名称praisonai--response-mode响应模式batch或streambatch--cors-origins逗号分隔的 CORS 来源无--allowed-origins安全校验允许的来源列表无--session-ttl会话存活时间秒3600--no-termination禁用客户端会话终止启用--resumability是否启用 SSE 可恢复性true--log-level日志级别debug / info / warning / errorinfo认证与最小权限auth 体系示例目录中的 mcp_auth_example.py 演示了完整认证体系对应praisonai.mcp_server.auth模块OAuth / OIDCOAuthConfig、OAuthManager、OIDCDiscovery支持标准授权码流程default_scopes[openid, profile, tools:read]API KeyAPIKeyAuth支持Bearer头校验可为每个 Key 声明作用域如tools:read、tools:call、resources:readScopeManager作用域校验与展开admin作用域可展开为全部权限校验失败返回 MCP 专用错误码INSUFFICIENT_SCOPE -32001见 server.py。服务器端还内置了 JSON-RPC 标准错误码映射PARSE_ERROR-32700、INVALID_REQUEST-32600、METHOD_NOT_FOUND-32601、INVALID_PARAMS-32602、INTERNAL_ERROR-32603。客户端接入配置Claude Desktop在~/.config/claude/claude_desktop_config.json中添加{ mcpServers: { praisonai: { command: praisonai, args: [mcp, serve, --transport, stdio] } } }Cursor在 Cursor 设置中添加相同配置{ mcpServers: { praisonai: { command: praisonai, args: [mcp, serve, --transport, stdio] } } }config-generate命令支持--client claude-desktop|cursor|vscode|windsurf直接生成对应客户端的配置文件并可指定--output输出路径与--transport。若需远程访问将args替换为[mcp, serve, --transport, http-stream, --port, 8080]并把url指向服务器地址。环境变量配置服务器调用 LLM 相关工具时需要设置对应提供商的 API Keyexport OPENAI_API_KEYyour_key export ANTHROPIC_API_KEYyour_key # 可选 export GOOGLE_API_KEYyour_key # 可选OPENAI_API_KEY是聊天补全等核心工具的必要项其余按需配置客户端示例注释中也明确说明这一点。服务器暴露的能力清单可用工具Tools运行praisonai mcp list-tools可查看全部工具核心包括praisonai.chat.completion— 与 LLM 对话praisonai.agent.chat— 与 Agent 对话praisonai.agent.run— 让 Agent 执行任务praisonai.workflow.run— 运行工作流praisonai.images.generate— 生成图像praisonai.audio.transcribe— 语音转写praisonai.embed.create— 创建 Embeddingpraisonai.memory.*— 记忆相关操作praisonai.knowledge.*— 知识库相关操作从 registry.py 的实现看工具注册采用懒加载机制register_lazy工具列表在首次list_all/get时才触发加载且通过RLock保证线程安全避免服务器启动时加载全部工具的开销。工具搜索与注解2025-11-25 新特性list-tools --json输出结构化 JSONtools search memory按关键词搜索tools info name查看详情tools schema name获取 JSON Schema。工具注解支持readOnlyHint、destructiveHint、idempotentHint、openWorldHint四类提示详见 src/praisonai/examples/mcp/README.md。分页支持tools/list、resources/list、prompts/list均支持不透明游标分页base64url 编码页面大小由服务器决定默认 50上限 100非法游标返回 JSON-RPC 错误码-32602可通过registry.list_paginated(cursor..., page_size...)在代码中使用。可用资源Resourcespraisonai://memory/sessions— 列出记忆会话praisonai://workflows— 列出可用工作流praisonai://tools— 列出可用工具praisonai://agents— 列出 Agent 配置praisonai://knowledge/sources— 列出知识源praisonai://config— 获取当前配置praisonai://mcp/status— 获取 MCP 服务器状态可用提示词Promptsdeep-research— 生成深度研究提示词code-review— 生成代码审查提示词workflow-auto— 生成工作流自动构建提示词guardrail-check— 生成护栏检查提示词context-engineering— 生成上下文工程提示词eval-criteria— 生成评估标准提示词agent-instructions— 生成 Agent 指令提示词提示词通过prompts/get获取支持参数化调用如客户端示例中deep-research接受topic与depth参数mcp_client_example.py。从零启动到验证的完整流程安装与确认安装 PraisonAI 后执行praisonai mcp doctor检查 MCP 服务器健康状态启动服务器本地集成用praisonai mcp serve --transport stdio网络集成用praisonai mcp serve --transport http-stream --port 8080生产环境建议加上--api-key YOUR_KEY配置客户端运行praisonai mcp config-generate --client claude-desktop生成配置或手动写入mcpServersJSON验证能力在客户端中调用praisonai.agent.run让 Agent 执行任务或直接体验deep-research提示词也可用python mcp_client_example.py以纯 HTTP 方式验证整条链路扩展自定义工具参考 custom_tools_server.py用register_tool把你的业务函数接入 MCP。整个 MCP 服务器的 CLI 行为均有测试覆盖例如 src/praisonai/tests/unit/mcp/test_mcp_cli.py 验证了命令路由与参数解析。这套实现让 PraisonAI 从一个 Python Agent 框架平滑扩展为标准化的 AI 工具服务端无论是接入桌面客户端还是构建自定义 AI 工作流都只需关注业务本身。【免费下载链接】PraisonAIPraisonAI — Hire a 24/7 AI Workforce. Stop writing boilerplate and start shipping autonomous self-improving agents that research, plan, code, and execute tasks. Deployed in 5 lines of code with built-in memory, RAG, and support for 100 LLMs.项目地址: https://gitcode.com/GitHub_Trending/pr/PraisonAI创作声明:本文部分内容由AI辅助生成(AIGC),仅供参考
返回列表