内容丰富的GraphQL MCP服务器
MCP服务器实现，为Contentful的内容交付API提供GraphQL查询功能，实现高效的内容检索和模式探索。
- 请注意：如果您对代码不感兴趣，只想在
Claude Desktop（或任何其他能够使用MCP服务器的工具），您不必 克隆此仓库，您可以在Claude桌面中设置它，请参阅一节 有关如何安装它的说明，请参阅“与Claude Desktop一起使用”。
特性
- GraphQL查询执行：针对Contentful的GraphQL API执行自定义GraphQL查询
- 模式探索：发现并理解您的内容模型结构
- GraphQL集合发现：列出您空间中所有可用的GraphQL查询集合
- 图式反思：获取特定内容类型的详细字段信息
- 查询生成示例：生成示例查询以帮助您开始
- 智能分页：通过内置分页功能高效处理大型数据集
- 代币灵活性：使用内容交付API（CDA）令牌进行安全的只读访问
GraphQL功能
此MCP服务器专为使用Contentful的GraphQL操作而设计，与REST API相比，它提供了一种更高效、更灵活的查询内容的方式。
关键利益
- 灵活的查询：仅检索所需的字段，减少响应大小并提高性能
- 嵌套引用：在没有多个API调用的情况下，在单个查询中获取相关内容
- 架构验证：查询在GraphQL模式可用时进行验证
- 高效的数据获取：减少数据的过度提取和不足提取
- 类型安全：利用GraphQL强大的类型系统来更好地构建查询
GraphQL工具
MCP服务器提供四个核心GraphQL工具：
1.列出内容类型(graphql_list_content_types)
在Contentful空间的GraphQL模式中发现所有可用的GraphQL查询集合。
{
spaceId: string, // Required: Your Contentful space ID
environmentId?: string, // Optional, defaults to "master"
cdaToken: string // Required: Content Delivery API token
}2.获取内容类型架构(graphql_get_content_type_schema)
获取特定内容类型的详细架构信息，包括所有字段、它们的类型和关系。
{
contentType: string, // Required: The name of the content type to explore
spaceId: string, // Required: Your Contentful space ID
environmentId?: string, // Optional, defaults to "master"
cdaToken: string // Required: Content Delivery API token
}3.获取示例查询(graphql_get_example)
为特定内容类型生成示例GraphQL查询，以帮助您理解查询结构。
{
contentType: string, // Required: The content type to generate an example for
includeRelations?: boolean, // Optional: Whether to include related content
spaceId: string, // Required: Your Contentful space ID
environmentId?: string, // Optional, defaults to "master"
cdaToken: string // Required: Content Delivery API token
}4.执行查询(graphql_query)
针对Contentful的GraphQL API执行自定义GraphQL查询。
{
query: string, // Required: The GraphQL query to execute
variables?: object, // Optional: Variables for parameterized queries
spaceId: string, // Required: Your Contentful space ID
environmentId?: string, // Optional, defaults to "master"
cdaToken: string // Required: Content Delivery API token
}GraphQL提示
MCP服务器包括两个有用的提示来指导GraphQL模式探索：
1.探索GraphQL模式(explore-graphql-schema)
指导您系统地探索GraphQL模式，并牢记特定目标。
explore-graphql-schema(goal: "articles about marketing")2.构建GraphQL查询(build-graphql-query)
帮助您为具有指定字段、筛选器和引用处理的特定内容类型构建自定义GraphQL查询。
build-graphql-query(contentType: "Article", fields: "title,body,publishDate", filters: "publishDate > 2023-01-01", includeReferences: true)配置
先决条件
- 在以下网址创建一个内容丰富的帐户 内容的
- 从您的空间设置生成内容交付API（CDA）令牌
环境变量
CONTENTFUL_DELIVERY_ACCESS_TOKEN/--delivery-token：您的内容交付API令牌（必需）SPACE_ID/--space-id：您的内容空间ID（必填）ENVIRONMENT_ID/--environment-id：环境ID（默认为“master”）ENABLE_HTTP_SERVER/--http：设置为“true”以启用HTTP/SSE模式HTTP_PORT/--port：HTTP服务器的端口（默认值：3000）HTTP_HOST/--http-host：HTTP服务器的主机（默认：localhost）
认证
此MCP服务器使用Content Delivery API（CDA）令牌对您的Contentful内容进行安全、只读访问。CDA令牌是首选，因为：
- 安全：只读访问可降低安全风险
- 演出：针对内容交付进行了优化
- GraphQL支持：原生支持GraphQL操作
- 缓存：更好的缓存功能可提高性能
重要：所有GraphQL工具都需要显式 spaceId 和 cdaToken 参数。在开发过程中可以使用环境变量以方便使用，但为了清晰和安全，这些工具总是需要显式传递这些参数。
使用Claude Desktop
您无需克隆此仓库即可使用此MCP，只需将其添加到 你的 claude_desktop_config.json:
添加或编辑 ~/Library/Application Support/Claude/claude_desktop_config.json 并添加以下行：
{
"mcpServers": {
"contentful-graphql": {
"command": "npx",
"args": ["-y", "@ivotoby/contentful-graphql-mcp-server"],
"env": {
"CONTENTFUL_DELIVERY_ACCESS_TOKEN": "",
"SPACE_ID": "",
"ENVIRONMENT_ID": "master"
}
}
}
}如果您的MCP客户端不支持设置环境变量，您还可以使用参数设置令牌：
{
"mcpServers": {
"contentful-graphql": {
"command": "npx",
"args": [
"-y",
"@ivotoby/contentful-graphql-mcp-server",
"--delivery-token",
"",
"--space-id",
"",
"--environment-id",
"master"
]
}
}
}通过Smithery安装
通过以下方式自动安装克劳德桌面版Contentful GraphQL MCP服务器 史密瑟里:
npx -y @smithery/cli install @ivotoby/contentful-graphql-mcp-server --client claude开发设置
如果您想使用Claude Desktop进行贡献和测试：
- 克隆存储库并安装依赖项：
git clone https://github.com/ivo-toby/contentful-mcp-graphql.git
cd contentful-mcp-graphql
npm install- 运行开发服务器：
npm run dev- 更新
claude_desktop_config.json直接引用该项目：
{
"mcpServers": {
"contentful-graphql": {
"command": "node",
"args": ["/path/to/contentful-mcp-graphql/bin/mcp-server.js"],
"env": {
"CONTENTFUL_DELIVERY_ACCESS_TOKEN": "",
"SPACE_ID": ""
}
}
}
}这允许您直接使用Claude在MCP服务器中测试修改。如果添加新的工具或资源，则需要重新启动Claude Desktop。
开发工具
MCP检查员
该项目包括一个用于开发和调试的MCP检查器工具：
- 检查模式：运行
npm run inspect开始检查员http://localhost:5173 - 观看模式：使用
npm run inspect-watch文件更改时自动重新启动检查器 - 视觉界面：通过web界面测试和调试MCP工具
- 实时测试：尝试GraphQL查询并立即查看响应
可用脚本
npm run build：构建项目npm run dev：开发模式，根据更改自动重建npm run inspect：启动MCP检查器npm run inspect-watch：以文件监视启动检查器npm run test：运行测试npm run lint：运行ESLintnpm run typecheck：运行TypeScript类型检查
运输方式
MCP服务器支持两种传输模式：
stdio传输（默认）
默认传输模式使用标准输入/输出流进行通信，非常适合与Claude Desktop等MCP客户端集成。
npx -y @ivotoby/contentful-graphql-mcp-server --delivery-token YOUR_TOKEN --space-id YOUR_SPACE_ID流式HTTP传输
对于基于web的集成或独立服务部署：
npx -y @ivotoby/contentful-graphql-mcp-server --delivery-token YOUR_TOKEN --space-id YOUR_SPACE_ID --http --port 3000StreamableHTTP实现遵循标准MCP协议规范，允许任何MCP客户端连接而无需特殊处理。
示例用法
基本内容查询
query {
entryCollection(limit: 5) {
items {
sys {
id
}
title
description
}
}
}带引用的查询
query {
articleCollection(limit: 3) {
items {
title
body
author {
name
bio
}
tagsCollection {
items {
name
}
}
}
}
}筛选查询
query {
articleCollection(where: { publishDate_gte: "2023-01-01" }, order: publishDate_DESC, limit: 10) {
items {
title
publishDate
slug
}
}
}错误处理
服务器为以下对象实现了全面的错误处理：
- CDA令牌的身份验证失败
- GraphQL查询无效
- 网络连接问题
- 架构自检错误
- 来自Contentful的API的速率限制
安全
此MCP服务器的设计考虑了安全性：
- 只读访问：仅将CDA令牌用于内容传递
- 无写入操作：无法修改或删除内容
- 代币范围界定：令牌的作用域为特定的空间和环境
- 输入验证：所有查询在执行前都经过验证
许可证
MIT许可证
贡献
欢迎投稿！请随时提交拉取请求。对于重大更改，请先打开一个问题来讨论您想要更改的内容。
支持
此MCP服务器由社区维护，Contentful不提供官方支持。对于问题和功能请求，请使用GitHub问题跟踪器。