Contentful GraphQL MCP Server

内容丰富的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)

配置

先决条件

1. 在以下网址创建一个内容丰富的帐户 内容的
2. 从您的空间设置生成内容交付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进行贡献和测试：

1. 克隆存储库并安装依赖项：

   git clone https://github.com/ivo-toby/contentful-mcp-graphql.git
   cd contentful-mcp-graphql
   npm install

1. 运行开发服务器：

   npm run dev

1. 更新 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：运行ESLint
• npm 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 3000

StreamableHTTP实现遵循标准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问题跟踪器。