敏捷CMS MCP服务器
此MCP（模型上下文协议）服务器为获取Agility CMS内容模型模式、内容数据、容器和资产提供了全面的工具，使使用Next.js和Agility构建网站时更容易与Claude一起工作。
先决条件
- Node.js>=18.19.0
- 具有管理API访问权限的有效Agility CMS实例
- 有效的Agility CMS身份验证凭据
设置
- 克隆和安装依赖关系：
cd agility-mcp-server
npm install- 配置环境变量：
建议将环境变量放入claude_desktop_config.json文件中，如下所示——不需要包含文件系统MCP服务器，但如果你这样做，它允许claude直接在你的代码库中使用Agility内容详细信息进行编码。
不幸的是，我还没有创建oAuth流，因此获取Bearer访问令牌的最佳方法是使用https://mgmt.aglty.io/swagger/index.html敏捷管理API游乐场，手动获取并填写。它将在24小时后过期，届时您需要更换它。
{
"mcpServers": {
"filesystem": {
"command": "npx",
"args": [
"-y",
"@modelcontextprotocol/server-filesystem",
"FILL-IN-YOUR-EXACT-PATH/agility-mcp-server"
]
},
"agility-mcp-server": {
"command": "node",
"args": ["FILL-IN-YOUR-EXACT-PATH/agility-mcp-server/dist/index.js"],
"env": {
"AGILITY_ACCESS_TOKEN": "your-token-here",
"AGILITY_WEBSITE_GUID": "your-guid-here",
"AGILITY_LOCALE": "en-us"
}
}
}
}以下方法也适用，但在访问令牌过期并被替换后，它通常会出现刷新问题——如果你有这个问题，那么使用上述方法，因为它无论如何都会取代.env文件。 复制 .env.example 向 .env 并填写您的Agility CMS凭据：
cp .env.example .env更新 .env 根据您的实际值：
AGILITY_ACCESS_TOKEN=your_access_token_here
AGILITY_CLIENT_ID=your_client_id_here
AGILITY_CLIENT_SECRET=your_client_secret_here
AGILITY_WEBSITE_GUID=your_website_guid_here
AGILITY_LOCALE=en-us- 构建项目：
npm run build可用工具
📊 内容模型工具
1.按引用名称获取内容模型
工具名称： get-content-model-by-reference-name 说明： 按引用名称获取敏捷CMS内容模型结构
输入：
referenceName（string）：要获取的内容模型的引用名称
示例用法：
Please use the get-content-model-by-reference-name tool to fetch the content model with reference name "blogposts"2.按ID获取内容模型
工具名称： get-content-model-by-id 说明： 通过数字ID获取敏捷CMS内容模型结构
输入：
id（number）：要获取的内容模型的数字ID
示例用法：
Please use the get-content-model-by-id tool to fetch the content model with ID 123📝 内容工具
3.获取内容项
工具名称： get-content-item 说明： 按ID获取特定内容项
输入：
contentID（number）：所请求内容项的内容IDlocale（string，可选）：内容的区域设置（默认为en-us）
示例用法：
Use the get-content-item tool to fetch content item with ID 40914.获取内容项
工具名称： get-content-items 说明： 使用可选筛选按容器引用名称获取内容项
输入：
referenceName（string）：内容容器的引用名称locale（string，可选）：内容的区域设置（默认为en-us）take（number，可选）：要检索的项目数（默认值：50）skip（number，可选）：分页时要跳过的项目数（默认值：0）sort（字符串，可选）：排序依据的字段名direction（'asc'|'desc'，可选）：排序方向（默认：'asc'）
示例用法：
Use the get-content-items tool to fetch the first 10 blog posts sorted by date: referenceName="blogposts", take=10, sort="date", direction="desc"5.获取内容列表（高级筛选）
工具名称： get-content-list 说明： 使用高级筛选选项获取筛选后的内容列表
输入：
referenceName（string）：内容容器的引用名称locale（string，可选）：内容的区域设置（默认为en-us）take（number，可选）：要检索的项目数（默认值：50）skip（number，可选）：分页时要跳过的项目数（默认值：0）sort（字符串，可选）：排序依据的字段名direction（'asc'|'desc'，可选）：排序方向（默认：'asc'）filters（对象，可选）：字段级过滤器作为键值对
示例用法：
Use the get-content-list tool to fetch published blog posts: referenceName="blogposts", filters={"status": "Published", "category": "Technology"}📦 容器工具
6.按ID获取容器
工具名称： get-container-by-id 说明： 通过内容容器的数字ID获取内容容器
输入：
id（number）：所请求容器的容器ID
示例用法：
Use the get-container-by-id tool to fetch container with ID 4567.按型号获取容器
工具名称： get-containers-by-model 说明： 获取使用特定内容模型ID的所有容器
输入：
modelId（number）：用于查找容器的型号ID
示例用法：
Use the get-containers-by-model tool to find all containers using model ID 1238.按引用名称获取容器
工具名称： get-container-by-reference-name 说明： 按内容容器的引用名称获取内容容器
输入：
referenceName（string）：要获取的容器的引用名称
示例用法：
Use the get-container-by-reference-name tool to fetch the "blogposts" container🖼️ 资产工具
9.按ID获取资产
工具名称： get-asset-by-id 说明： 按媒体ID获取资产
输入：
mediaID（number）：所请求资产的媒体ID
示例用法：
Use the get-asset-by-id tool to fetch asset with media ID 78910.通过URL获取资产
工具名称： get-asset-by-url 说明： 按URL获取资产
输入：
url（string）：所请求资产的URL
示例用法：
Use the get-asset-by-url tool to fetch asset from "https://agility-cms.s3.amazonaws.com/my-instance/logo.png"与Claude Desktop一起使用
将此服务器添加到您的Claude Desktop配置中：
macOS： ~/Library/Application Support/Claude/claude_desktop_config.json 窗户： %APPDATA%/Claude/claude_desktop_config.json
{
"mcpServers": {
"agility-mcp-server": {
"command": "node",
"args": ["/absolute/path/to/agility-mcp-server/dist/index.js"]
}
}
}替换 /absolute/path/to/agility-mcp-server 带有项目目录的实际路径。
认证
这些工具使用OAuth 2.0身份验证和Agility CMS。您需要：
- 通过Agility CMS管理API OAuth流生成访问令牌
- 更新
AGILITY_ACCESS_TOKEN在你的.env需要时归档 - 访问令牌通常在1小时后过期
现在，您可以在 .env 文件过期时。这些工具包括身份验证失败的错误处理。
错误处理
所有工具都包括全面的错误处理，用于：
- 缺少环境变量
- 身份验证失败（401个错误）
- 找不到资源（404错误）
- 网络和API错误
发展
- 观看模式：
npm run watch - 构建：
npm run build - 开始：
npm start - 测试连接：
npm test
项目结构
src/
├── tools/
│ ├── models/ # Content model tools
│ │ ├── NamedContentModelTool.ts
│ │ └── ContentmodelbyidTool.ts
│ ├── content/ # Content management tools
│ │ ├── GetContentItemTool.ts
│ │ ├── GetContentItemsTool.ts
│ │ └── GetContentListTool.ts
│ ├── containers/ # Container management tools
│ │ ├── GetContainerByIdTool.ts
│ │ ├── GetContainersByModelTool.ts
│ │ └── GetContainerByReferenceNameTool.ts
│ └── assets/ # Asset management tools
│ ├── GetAssetByIdTool.ts
│ └── GetAssetByUrlTool.ts
└── index.ts常见工作流
1.探索内容结构
1. Use get-content-model-by-reference-name to understand content fields
2. Use get-container-by-reference-name to get container details
3. Use get-content-items to fetch actual content2.内容分析
1. Use get-content-list with filters to find specific content
2. Use get-content-item to get detailed content information
3. Use get-asset-by-id to get related media details3.模型发现
1. Use get-content-model-by-id to inspect model structure
2. Use get-containers-by-model to find where models are used
3. Use get-content-items to see content examples使用敏捷管理SDK
所有工具都使用 @agility/management-sdk 使用此模式：
import * as mgmtApi from '@agility/management-sdk';
// Initialize API client
const options = new mgmtApi.Options();
options.token = process.env.AGILITY_ACCESS_TOKEN;
const apiClient = new mgmtApi.ApiClient(options);
// Make API calls
const guid = process.env.AGILITY_WEBSITE_GUID;
const locale = process.env.AGILITY_LOCALE || 'en-us';后续步骤
考虑添加以下附加工具：
- 页面模板管理工具
- 内容创建/更新工具
- 批量内容操作
- 资产上传和管理
- 工作流程和审批工具
支持
有关此MCP服务器的问题，请查看GitHub存储库。 有关Agility CMS的具体问题，请访问 敏捷开发者社区.