AI导哈

Frappe MCP服务器

一个为Frappe框架设计的模型上下文协议（MCP）服务器，通过官方REST API向AI助手暴露Frappe的功能，专注于文档CRUD操作、模式处理和详细的API指令。

  • by ArtemZhigarev
  • 本地部署
  • 更新于
在 GitHub 查看 artemzhigarev/frappe_mcp_server

使用说明

Frappe MCP服务器

Frappe框架的模型上下文协议（MCP）服务器，通过官方REST API向人工智能助手展示Frappe的功能，重点关注文档CRUD操作、模式处理和详细的API指令。

概述

该MCP服务器允许AI助手通过使用官方Frappe REST API的标准化界面与Frappe应用程序进行交互。它提供了以下工具：

  • 文档操作（创建、读取、更新、删除、列出）
  • 模式和元数据处理
  • DocType发现和探索
  • API详细使用说明和示例

该服务器包括全面的错误处理、验证和有用的响应，使人工智能助手更容易使用Frappe。

运输支持

服务器支持多种传输协议：

  • 标准输入输出 （默认）：用于与Claude Desktop和其他MCP客户端本地集成的标准输入/输出
  • 超文本传输协议：RESTful HTTP端点和MCP JSON-RPC over HTTP用于基于web的集成（端口51966/0xCAFE）
  • 流式HTTP：现代MCP传输，可选SSE流，用于实时更新（端口51953/0xCAF1）

安装

先决条件

  • Node.js 18或更高版本
  • 正在运行的Frappe实例（版本15或更高）
  • 来自Frappe的API密钥和秘密(必需的)

设置

  1. 通过npm安装：
npm install -g frappe-mcp-server

或者，直接使用npx运行：

npx frappe-mcp-server

（无需安装）

配置

使用环境变量配置服务器：

  • FRAPPE_URL：Frappe实例的URL（默认值： http://localhost:8000)
  • FRAPPE_API_KEY：您的Frappe API密钥(必需的)
  • FRAPPE_API_SECRET：您的Frappe API秘密(必需的)

重要：API密钥/机密身份验证是唯一支持的身份验证方法。两者 FRAPPE_API_KEY 和 FRAPPE_API_SECRET 必须为服务器正常运行提供。不支持用户名/密码身份验证。

认证

此MCP服务器 仅支持API密钥/秘密身份验证 通过Frappe REST API。不支持用户名/密码身份验证。

正在获取API凭据

要从您的Frappe实例获取API凭据，请执行以下操作：

  1. 前往用户>API访问>新建API密钥
  2. 选择要为其创建密钥的用户
  3. 点击“生成密钥”
  4. 复制API密钥和API机密

身份验证故障排除

如果遇到身份验证错误：

  1. 验证两者 FRAPPE_API_KEY 和 FRAPPE_API_SECRET 环境变量设置正确
  2. 确保API密钥在Frappe实例中处于活动状态且未过期
  3. 检查与API密钥关联的用户是否具有必要的权限
  4. 验证Frappe URL是否正确且可访问

服务器提供详细的错误消息以帮助诊断身份验证问题。

用法

启动服务器

stdio传输（默认）

npx frappe-mcp-server

或者使用环境变量：

FRAPPE_URL=https://your-frappe-instance.com FRAPPE_API_KEY=your_api_key FRAPPE_API_SECRET=your_api_secret npx frappe-mcp-server

HTTP传输

要使用HTTP传输启动服务器，请执行以下操作：

npm run start-http

HTTP服务器在端口51966（0xCAFE）上运行，并提供：

  • 用于直接HTTP集成的RESTful端点
  • MCP JSON-RPC协议支持
  • 健康检查和服务器信息端点

可用HTTP端点：

  • GET /health -健康检查
  • GET /info -服务器信息
  • GET /tools -列出可用工具
  • POST /call/:tool -调用特定工具
  • POST / -MCP JSON-RPC端点

流式HTTP传输（推荐）

要使用Streamable HTTP传输启动服务器，请执行以下操作：

npm run start-streamable

Streamable HTTP服务器在端口51953（0xCAF1）上运行，并提供：

  • 现代MCP协议支持（2024-11-05版）
  • 自动内容协商（JSON或SSE）
  • 具有自动清理功能的状态会话
  • 长时间运行操作的实时流媒体
  • 连接健康的心跳机制

特征：

  • 单端点：所有MCP操作通过 POST /
  • 可选流媒体：客户端可以通过设置请求SSE Accept: text/event-stream
  • 会话管理：具有会话ID的有状态操作
  • 进度更新：长时间运行的工具的实时进度

与AI助手集成

要将此MCP服务器与AI助手一起使用，您需要配置助手以连接到此服务器。确切的配置取决于您使用的AI助手平台。

克劳德桌面（stdio传输）

对于Claude Desktop，请将以下内容添加到MCP设置配置文件中：

{
  "mcpServers": {
    "frappe": {
      "command": "npx",
      "args": ["frappe-mcp-server"],
      "env": {
        "FRAPPE_URL": "https://your-frappe-instance.com",
        "FRAPPE_API_KEY": "your_api_key", // REQUIRED
        "FRAPPE_API_SECRET": "your_api_secret" // REQUIRED
      },
      "disabled": false,
      "alwaysAllow": []
    }
  }
}

备注：两者都有 FRAPPE_API_KEY 和 FRAPPE_API_SECRET 需要环境变量。服务器将在没有它们的情况下启动，但大多数操作都会因身份验证错误而失败。

远程MCP服务器（可流式HTTP传输）

对于Claude Pro/Max/Teams/Enterprise用户，您可以部署Streamable HTTP服务器并将其添加为远程MCP服务器：

  1. 将Streamable HTTP服务器部署到公共URL
  2. 在Claude Desktop中，转到“设置”>“集成”
  3. 添加您的MCP服务器URL

重要：Claude Desktop目前仅支持通过以下方式配置的本地MCP服务器的stdio传输 claude_desktop_config.json。必须通过设置界面添加远程HTTP/Streamable服务器。

其他MCP客户端

对于支持HTTP传输的MCP客户端，请使用您的服务器URL对其进行配置：

标准HTTP（传统）：

http://localhost:51966

流式HTTP（推荐）：

http://localhost:51953

或者对于生产部署：

https://your-mcp-server.com

建议使用流式HTTP传输，因为它：

  • 支持最新的MCP协议（2024-11-05）
  • 提供自动内容协商
  • 支持长时间操作的实时流媒体
  • 维护有状态会话

可用工具

文档操作

  • create_document：在Frappe中创建新文档
  • get_document：从Frappe检索文档
  • update_document：更新Frappe中的现有文档
  • delete_document：从Frappe中删除文档
  • list_documents：使用过滤器列出Frappe的文档

架构操作

  • get_doctype_schema：获取DocType的完整架构，包括字段定义、验证和链接的DocType
  • get_field_options：获取链接或选择字段的可用选项
  • get_frappe_usage_info：获取有关DocType或工作流的组合信息，包括模式元数据、静态提示和应用程序提供的使用指南

辅助工具

  • find_doctypes：在系统中查找与搜索词匹配的DocTypes
  • get_module_list：获取系统中所有模块的列表
  • get_doctypes_in_module：获取特定模块中的DocType列表
  • check_doctype_exists：检查系统中是否存在DocType
  • check_document_exists：检查文档是否存在
  • get_document_count：获取符合筛选条件的文档数量
  • get_naming_info：获取DocType的命名系列信息
  • get_required_fields：获取DocType的必填字段列表
  • get_api_instructions：获取有关使用Frappe API的详细说明

可用资源

架构资源

  • schema://{doctype}：DocType的架构信息
  • schema://{doctype}/{fieldname}/options：链接或选择字段的可用选项
  • schema://modules：系统中所有模块的列表
  • schema://doctypes：系统中所有DocType的列表

特性

使用信息增强

服务器通过结合三个来源提供全面的使用信息：

  1. Metadata打字：直接从Frappe API检索的架构信息
  2. 静态提示：存储在JSON文件中的补充上下文 static_hints/ 目录
  3. 自定义应用程序反思：自定义Frappe应用程序直接提供的使用说明

这一增强功能使人工智能助手能够更好地理解Frappe模块，使其更有效地帮助用户使用基于Frappe的应用程序。

有关更多详细信息，请参阅 使用信息增强.

例子

创建文档

// Example of using the create_document tool
const result = await useToolWithMcp("frappe", "create_document", {
  doctype: "Customer",
  values: {
    customer_name: "John Doe",
    customer_type: "Individual",
    customer_group: "All Customer Groups",
    territory: "All Territories",
  },
});

获取文档

// Example of using the get_document tool
const customer = await useToolWithMcp("frappe", "get_document", {
  doctype: "Customer",
  name: "CUST-00001",
  fields: ["customer_name", "customer_type", "email_id"], // Optional: specific fields
});

使用筛选器列出文档

// Example of using the list_documents tool with filters
const customers = await useToolWithMcp("frappe", "list_documents", {
  doctype: "Customer",
  filters: {
    customer_type: "Individual",
    territory: "United States",
  },
  fields: ["name", "customer_name", "email_id"],
  limit: 10,
  order_by: "creation desc",
});

查找文档类型

// Example of using the find_doctypes tool
const salesDocTypes = await useToolWithMcp("frappe", "find_doctypes", {
  search_term: "Sales",
  module: "Selling",
  is_table: false,
});

获取必填字段

// Example of using the get_required_fields tool
const requiredFields = await useToolWithMcp("frappe", "get_required_fields", {
  doctype: "Sales Order",
});

获取API说明

// Example of using the get_api_instructions tool
const instructions = await useToolWithMcp("frappe", "get_api_instructions", {
  category: "DOCUMENT_OPERATIONS",
  operation: "CREATE",
});

获取使用信息

// Example of using the get_frappe_usage_info tool
const salesOrderInfo = await useToolWithMcp("frappe", "get_frappe_usage_info", {
  doctype: "Sales Order",
});

// Example of getting workflow information
const workflowInfo = await useToolWithMcp("frappe", "get_frappe_usage_info", {
  workflow: "Quote to Sales Order Conversion",
});

错误处理

服务器提供详细的错误消息和上下文，以帮助诊断问题：

  • 缺少必要参数
  • 字段值无效
  • 权限错误
  • 网络问题
  • 服务器错误

每个错误包括：

  • 描述性信息
  • HTTP状态码（如适用）
  • 端点信息
  • Frappe服务器的其他详细信息

最佳实践

  1. 首先检查DocType架构：在创建或更新文档之前，请先了解架构以了解所需的字段和验证。

  2. 使用分页：列出文件时，使用 limit 和 limit_start 用于对结果进行分页的参数。

  3. 指定字段：只请求提高性能所需的字段。

  4. 创建前验证：使用 get_required_fields 在创建文档之前，确保您拥有所有必填字段。

  5. 检查是否存在：使用 check_document_exists 在更新或删除以确保文档存在之前。

许可证

国际协调委员会

相关 MCP