星战科技xingzhan.cloud
返回市场
斯特拉pi-mcp

斯特拉pi-mcp

作者：l33tdawg21 星标更新：2025-07-25
安装使用来源：spider==github.com

项目介绍

技术文档摘要

Strapi MCP

一个用于Strapi CMS的MCP服务器，通过模型上下文协议提供对内容类型和条目的访问。

概述

此MCP服务器与任何Strapi CMS实例集成，以提供以下功能：

  • 作为资源访问Strapi内容类型
  • 创建和更新Strapi内容类型的工具
  • 管理内容条目（创建、读取、更新、删除）的工具
  • 支持Strapi的开发模式
  • 强大的错误处理，具有清晰的诊断和故障排除指南
  • 配置验证，以防止常见的设置问题

安装

环境变量

建议在项目根目录中使用.env文件来存储您的凭据。

  • STRAPI_URL: 您的Strapi实例的URL（默认：http://localhost:1337）
  • STRAPI_ADMIN_EMAIL: Strapi管理员用户的电子邮件地址（推荐用于完整功能，特别是模式访问）
  • STRAPI_ADMIN_PASSWORD: Strapi管理员用户的密码（推荐）
  • STRAPI_API_TOKEN: （可选备用）API令牌。如果未提供管理员凭据，可以使用，但可能权限有限。
  • STRAPI_DEV_MODE: 设置为"true"以启用开发模式功能（默认为false）

示例.env文件：

STRAPI_URL=http://localhost:1337
STRAPI_ADMIN_EMAIL=your_admin_email@example.com
STRAPI_ADMIN_PASSWORD=your_admin_password
# STRAPI_API_TOKEN=your_api_token_here # 可选

重要事项：

  • 将.env添加到.gitignore文件中，以避免提交凭据
  • 避免使用如"strapi_token"这样的占位符值——服务器会验证并拒绝常见的占位符

安装

从npm安装（推荐）

npm install strapi-mcp

从源代码安装（开发）

为了获取最新的开发功能：

git clone https://github.com/l33tdawg/strapi-mcp.git
cd strapi-mcp
npm install
npm run build

运行

推荐方法（使用Cursor MCP配置）：

对于Cursor用户，在您的~/.cursor/mcp.json文件中配置strapi-mcp服务器：

"strapi-mcp": {
  "command": "npx",
  "args": ["strapi-mcp"], 
  "env": {
    "STRAPI_URL": "http://localhost:1337",
    "STRAPI_ADMIN_EMAIL": "your_admin_email@example.com",
    "STRAPI_ADMIN_PASSWORD": "your_admin_password"
  }
}

如果您是从源代码安装的，请使用直接路径：

"strapi-mcp": {
  "command": "node",
  "args": ["/path/to/strapi-mcp/build/index.js"], 
  "env": {
    "STRAPI_URL": "http://localhost:1337",
    "STRAPI_ADMIN_EMAIL": "your_admin_email@example.com",
    "STRAPI_ADMIN_PASSWORD": "your_admin_password"
  }
}

当使用strapi-mcp工具时，Cursor将自动管理服务器生命周期。

替代方法（使用.env文件）：

确保已构建项目（npm run build）。然后使用Node.js v20.6.0+和--env-file标志运行服务器：

node --env-file=.env build/index.js

替代方法（直接使用环境变量）：

export STRAPI_URL=http://localhost:1337
export STRAPI_ADMIN_EMAIL=your_admin_email@example.com
export STRAPI_ADMIN_PASSWORD=your_admin_password
# export STRAPI_API_TOKEN=your-api-token # 可选备用
export STRAPI_DEV_MODE=true # 可选

# 运行全局安装的包（如果通过npm install -g安装）
strapi-mcp 
# 或直接运行本地构建
node build/index.js

功能

  • 列出和读取内容类型
  • 获取、创建、更新和删除条目
  • 上传媒体文件
  • 连接和断开关系
  • 获取内容类型模式

更新日志

0.2.3 - 2025-07-25

  • 关键修复： 修复了关系工具中的超时问题 - connect_relation 和 disconnect_relation 现在正确处理验证错误而不是超时
  • 改进的错误处理： 所有验证错误现在返回正确的错误消息而不是导致工具超时

0.2.2 - 2025-07-25

  • 增强的关系工具： 提高了 connect_relation 和 disconnect_relation 的错误处理，带有详细的验证和故障排除信息
  • 修复了CREATE_COMPONENT： 修复了参数验证错误 - 现在正确地验证单个参数而不是单个对象
  • 更好的错误诊断： 添加了针对无效关系字段、不存在的条目和畸形ID的具体错误消息
  • 所有20个工具现在都具备100%的健壮错误处理和验证

0.2.0 - 2025-07-25

  • 关键错误修复： 修复了validateStrapiConnection导致的“未定义响应状态”错误
  • 解决了MCP连接问题： 解决了“绿灯但不起作用”的AI工具问题
  • 改进的错误处理： 更好的连接验证逻辑，以及适当的管理员身份验证处理
  • 如果遇到AI工具的MCP连接问题，用户应升级到此版本

0.1.9 - 2025-07-02

  • 上下文窗口溢出修复： 添加了大小限制和响应过滤，以防止base64文件淹没上下文窗口
  • 新工具： 添加了upload_media_from_path - 从本地文件路径上传文件（最大10MB），以避免base64上下文问题
  • 增强了UPLOAD_MEDIA： 添加了1MB base64大小限制（约750KB文件），并提供了关于上下文溢出的明确错误消息
  • 改进的日志记录： 截断日志中的base64数据，以防止日志垃圾邮件和上下文溢出
  • 响应过滤： 自动过滤API响应中的大型base64字符串，以防止回声溢出

0.1.8 - 2025-06-12

  • 重大错误修复： 当无法获取内容类型或条目时，用描述性错误消息替换了静默失败
  • 添加了配置验证： 检测占位符API令牌，并带有有用的错误消息退出
  • 添加了连接验证： 在尝试操作之前测试Strapi连接，带有特定的错误诊断
  • 增强了错误处理： 区分实际空集合与实际错误的全面错误诊断
  • 改进了故障排除： 所有错误消息都包括解决常见配置问题的具体步骤

0.1.7 - 2025-05-17

  • 添加了publish_entry和unpublish_entry工具： 完整的内容生命周期管理
  • 添加了组件管理： list_components，get_component_schema，create_component，update_component
  • 添加了delete_content_type工具： 通过内容类型生成器API删除现有内容类型
  • 增强了管理员身份验证： 所有API操作的更好错误处理和令牌管理

0.1.6

  • 添加了create_content_type工具： 允许通过内容类型生成器API创建新的内容类型（需要管理员凭据）。
  • 优先使用管理员凭据： 更新逻辑以优先使用管理员电子邮件/密码来获取内容类型和模式，提高可靠性。
  • 更新了文档： 澄清了身份验证方法并推荐了运行程序。

0.1.5

  • 改进了具有多种备用方法的内容类型发现
  • 添加了更强大的错误处理和日志记录
  • 增强了内容类型的模式推断

0.1.4

  • 改进了具有更多具体错误代码的错误处理
  • 添加了ResourceNotFound和AccessDenied错误代码
  • 对常见API错误的更好错误消息

0.1.3

  • 初始公开发布

许可证

MIT

strapi-mcp MCP服务器

一个用于您Strapi CMS的MCP服务器

这是一个基于TypeScript的MCP服务器，与Strapi CMS集成。它通过MCP协议提供对Strapi内容类型和条目的访问，允许您：

  • 作为资源访问Strapi内容类型
  • 创建、读取、更新和删除内容条目
  • 通过MCP工具管理您的Strapi内容

功能

资源

  • 通过strapi://content-type/URI列表和访问内容类型
  • 每个内容类型将其条目暴露为JSON
  • 使用application/json MIME类型进行结构化内容访问

工具

  • list_content_types - 列出Strapi中所有可用的内容类型
  • get_entries - 获取特定内容类型的内容条目，可选过滤、分页、排序和关联关系填充
  • get_entry - 根据ID获取特定条目
  • create_entry - 为内容类型创建新条目
  • update_entry - 更新现有条目
  • delete_entry - 删除条目
  • upload_media - 将媒体文件上传到Strapi（最大约750KB文件，由于base64上下文限制）
  • upload_media_from_path - 从本地文件路径上传媒体文件（最大10MB，避免上下文溢出）
  • get_content_type_schema - 获取特定内容类型的模式（字段、类型、关系）
  • connect_relation - 将相关条目连接到条目的关系字段
  • disconnect_relation - 断开条目的关系字段的相关条目
  • create_content_type - 使用内容类型生成器API创建新的内容类型（需要管理员权限）
  • publish_entry - 发布特定条目
  • unpublish_entry - 取消发布特定条目
  • list_components - 列出Strapi中所有可用的组件
  • get_component_schema - 获取特定组件的模式
  • create_component - 创建新的组件
  • update_component - 更新现有的组件

高级功能

过滤、分页和排序

get_entries工具支持高级查询选项：

{
  "contentType": "api::article.article",
  "filters": {
    "title": {
      "$contains": "hello"
    }
  },
  "pagination": {
    "page": 1,
    "pageSize": 10
  },
  "sort": ["title:asc", "createdAt:desc"],
  "populate": ["author", "categories"]
}

资源URI

可以通过各种URI格式访问资源：

  • strapi://content-type/api::article.article - 获取所有文章
  • strapi://content-type/api::article.article/1 - 获取ID为1的文章
  • strapi://content-type/api::article.article?filters={"title":{"$contains":"hello"}} - 获取过滤后的文章

发布和取消发布内容

publish_entry和unpublish_entry工具提供了对内容生命周期的控制：

{
  "contentType": "api::article.article",
  "id": "1"
}

这些工具利用管理员API路径进行发布/取消发布操作，如果没有管理员权限，则会回退到直接更新publishedAt字段。

组件管理

可以使用以下工具管理Strapi组件：

  • list_components：获取所有可用的组件
  • get_component_schema：查看特定组件的结构
  • create_component：使用指定字段创建新的组件
  • update_component：修改现有的组件

创建组件的示例：

{
  "componentData": {
    "displayName": "安全设置",
    "category": "security",
    "icon": "shield",
    "attributes": {
      "enableTwoFactor": {
        "type": "boolean", 
        "default": false
      },
      "passwordExpiration": {
        "type": "integer",
        "min": 
      }
    }
  }
}

开发

安装依赖项：

npm install

构建服务器：

npm run build

开发时自动重建：

npm run watch

安装

要详细了解如何部署和测试此MCP服务器的详细步骤，请参阅DEPLOYMENT.md文件。

快速设置：

  1. 构建服务器：npm run build
  2. 配置您的Strapi实例并获取API令牌
  3. 将服务器配置添加到Claude Desktop：

在MacOS上：~/Library/Application Support/Claude/claude_desktop_config.json 在Windows上：%APPDATA%/Claude/claude_desktop_config.json

{
  "mcpServers": {
    "strapi-mcp": {
      "command": "npx",
      "args": ["strapi-mcp"],
      "env": {
        "STRAPI_URL": "http://localhost:1337",
        "STRAPI_ADMIN_EMAIL": "your_admin_email@example.com",
        "STRAPI_ADMIN_PASSWORD": "your_admin_password"
      }
    }
  }
}

如果您是从源代码安装的，请使用直接路径：

{
  "mcpServers": {
    "strapi-mcp": {
      "command": "/path/to/strapi-mcp/build/index.js",
      "env": {
        "STRAPI_URL": "http://localhost:1337",
        "STRAPI_ADMIN_EMAIL": "your_admin_email@example.com",
        "STRAPI_ADMIN_PASSWORD": "your_admin_password"
      }
    }
  }
}

环境变量

  • STRAPI_URL（可选）：您的Strapi实例的URL（默认为http://localhost:1337）
  • STRAPI_ADMIN_EMAIL & STRAPI_ADMIN_PASSWORD（推荐）：Strapi管理员用户的凭据。完整功能（如获取内容类型模式）所需。
  • STRAPI_API_TOKEN（可选备用）：您的Strapi API令牌。如果未提供管理员凭据，可以使用，但功能可能受限于令牌权限。
  • STRAPI_DEV_MODE（可选）：设置为"true"以启用开发模式功能（默认为false）

认证优先级

服务器按以下顺序优先认证方法：

  1. 管理员电子邮件和密码（STRAPI_ADMIN_EMAIL，STRAPI_ADMIN_PASSWORD）
  2. API令牌（STRAPI_API_TOKEN）

强烈建议使用管理员凭据以获得最佳效果。

获取Strapi凭据

  • 管理员凭据： 使用现有超级管理员的电子邮件和密码，或在您的Strapi管理面板中创建专用管理员用户（设置 > 管理面板 > 用户）。
  • API令牌： （可选备用）
  1. 登录到您的Strapi管理面板
  2. 转到设置 > API令牌
  3. 单击“创建新API令牌”
  4. 设置名称、描述和令牌类型（优选“完全访问”）
  5. 复制生成的令牌并在您的MCP服务器配置中使用

故障排除

常见问题及解决方案：

1. 占位符API令牌错误

[Error] STRAPI_API_TOKEN似乎是一个占位符值...

解决方案： 将"strapi_token"或"your-api-token-here"替换为您从Strapi管理面板获取的真实API令牌。

2. 连接被拒绝错误

无法连接到Strapi实例：连接被拒绝。Strapi是否正在http://localhost:1337运行？

解决方案：

  • 确保Strapi正在运行：npm run develop或yarn develop
  • 检查STRAPI_URL中的URL是否正确
  • 验证您的数据库（MySQL/PostgreSQL）是否正在运行

3. 身份验证失败

无法连接到Strapi实例：身份验证失败。检查您的API令牌或管理员凭据。

解决方案：

  • 验证您的API令牌具有适当的权限（优选“完全访问”）
  • 检查管理员电子邮件/密码是否正确
  • 确认管理员用户存在且处于活动状态

4. 上下文窗口溢出与文件上传

错误：由于大型base64字符串导致上下文窗口溢出

问题： base64编码的文件可能非常大（即使是小图片也可能达到50-100KB文本），导致上下文窗口溢出。

解决方案：

  • 使用upload_media_from_path代替upload_media 用于大于约500KB的文件
  • 减少文件大小 上传前（压缩图像，降低分辨率）
  • 使用较小的文件 - upload_media工具具有1MB base64限制（约750KB文件）

5. 虚假内容类型（api::data.data，api::error.error）

此问题已在v0.1.8中修复。如果您仍然看到这些，您可能正在使用旧版本。

6. 空结果与错误

自v0.1.8起，服务器现在清楚地区分：

  • 空集合（内容类型存在但没有条目）→ 返回{"data": [], "meta": {...}}
  • 实际错误（内容类型不存在，身份验证失败等）→ 抛出带有故障排除步骤的描述性错误

7. 权限错误

访问被禁止。您的API令牌可能缺乏必要的权限。

解决方案：

  • 使用管理员凭据而不是API令牌以实现完整功能
  • 如果使用API令牌，请确保其具有“完全访问”权限
  • 检查内容类型是否允许公共访问，如果使用的是有限API令牌

调试

由于MCP服务器通过stdio通信，调试可能会很困难。我们建议使用[MCP Inspector](https://github