CulturAllyAI MCP服务器
模型上下文协议（MCP）服务器 为文化活动管理提供只读工具。
这是一个教育项目，旨在通过实现一个简单的服务器来了解MCP架构，该服务器公开了4个用于处理CulturAllyAI平台事件数据的工具。
______________________________________________________________________
📋 目录
______________________________________________________________________
🎯 概述
CulturAllyAI MCP服务器 是一个独立的MCP服务器，提供对以下内容的只读访问：
- 活动类别列表（8种文化活动类型）
- 年龄类别列表（7个年龄组）
- 使用全面的业务规则进行事件数据验证
- 日期格式化实用程序（ISO 8601至YYYY-MM-DD）
此服务器是 完全分开 来自CulturAllyAI主应用程序，不包含AI生成、数据库访问或身份验证。它被设计为一个学习练习，以了解MCP协议的实现。
关键特性
- ✅ 只读操作 -无数据修改
- ✅ 无状态 -没有数据库连接
- ✅ 对主应用程序零依赖 -完全隔离
- ✅ 类型安全 -带有严格模式的完整TypeScript
- ✅ 经过充分测试 -114个单元测试，覆盖率超过93%
- ✅ 符合MCP标准 -使用官方
@modelcontextprotocol/sdk
______________________________________________________________________
✨ 特性
1.事件类别
返回8个带有波兰标签的文化活动类别：
- 音乐会（Concerts）
- 活动（Events）
- 戏剧与舞蹈
- 艺术与展览（Art & Exhibitions）
- 文学（文学）
- 奇诺（电影院）
- Festiwale（节日）
- Inne（其他）
2.年龄类别
返回7个具有波兰标签和年龄范围的年龄组：
- 所有年龄段（All Ages）
- 最小（0-3岁）
- 儿童（4-12岁）
- 青少年（13-17岁）
- 年轻人（18-35岁）
- 成人（36-64岁）
- 老年人（65+岁）
3.事件数据验证
使用Zod模式进行全面验证：
- 标题：1-100个字符，已修剪
- 城市：1-50个字符，已修剪
- 活动日期：ISO 8601格式，必须是现在或将来
- 类别：必须是8个事件类别之一
- 年龄类别：必须是7个年龄组中的一个
- 关键信息：1-200个字符，已修剪
返回带有波兰语错误消息的结构化验证结果。
4.日期格式
将ISO 8601日期时间字符串转换为YYYY-MM-DD格式：
- 验证日期格式
- 从日期时间中提取日期部分
- 返回格式化日期或详细错误
______________________________________________________________________
🏗️ 建筑
┌─────────────────────────────────────────────────────────┐
│ MCP Client │
│ (Claude Desktop, Inspector, etc.) │
└───────────────────────┬─────────────────────────────────┘
│
│ stdio transport
│ (JSON-RPC 2.0)
│
┌───────────────────────▼─────────────────────────────────┐
│ CulturAllyAI MCP Server │
│ │
│ ┌─────────────────────────────────────────────────┐ │
│ │ Server (index.ts) │ │
│ │ - ListToolsRequestSchema handler │ │
│ │ - CallToolRequestSchema handler │ │
│ └───────────────────┬─────────────────────────────┘ │
│ │ │
│ ┌───────────────────▼─────────────────────────────┐ │
│ │ Tool Router (handlers.ts) │ │
│ │ - handleToolCall (central dispatcher) │ │
│ │ - handleGetEventCategories │ │
│ │ - handleGetAgeCategories │ │
│ │ - handleValidateEventData │ │
│ │ - handleFormatEventDate │ │
│ └───────────────────┬─────────────────────────────┘ │
│ │ │
│ ┌──────────────────┬▼────────────────────────────┐ │
│ │ │ │ │
│ │ Utils │ Validators │ │
│ │ - categories │ - Zod schemas │ │
│ │ - formatters │ - Event validation │ │
│ │ - date-helpers │ - Error formatting │ │
│ └──────────────────┴─────────────────────────────┘ │
└─────────────────────────────────────────────────────────┘组件
- 服务器入口点 (
src/index.ts)
- 使用stdio传输初始化MCP服务器 - 为ListTools和CallTool注册请求处理程序 - 管理服务器生命周期
- 工具定义 (
src/tools/definitions.ts)
- 所有4个工具的JSON模式定义 - 具有验证规则的参数模式 - 工具元数据（名称、描述）
- 工具操作员 (
src/tools/handlers.ts)
- 中央路由器(handleToolCall) - 单个工具执行功能 - 错误处理和响应格式
- 公用事业 (
src/utils/)
- 类别.ts：静态类别数据 - formatters.ts：MCP响应格式 - 日期-帮助者.ts：日期转换实用程序 - 验证器.ts：Zod验证模式
______________________________________________________________________
🛠️ 可用工具
1. get-event-categories
返回可用事件类别的列表。
参数： 无
答复：
{
"categories": [
{ "value": "koncerty", "label": "Koncerty" },
{ "value": "imprezy", "label": "Imprezy" },
...
]
}______________________________________________________________________
2. get-age-categories
返回可用年龄类别的列表。
参数： 无
答复：
{
"categories": [
{ "value": "wszystkie", "label": "Wszystkie" },
{ "value": "najmlodsi", "label": "Najmłodsi (0-3 lata)" },
...
]
}______________________________________________________________________
3. validate-event-data
根据全面的业务规则验证事件数据。
参数：
{
title: string; // 1-100 characters
city: string; // 1-50 characters
event_date: string; // ISO 8601, today or future
category: string; // One of 8 event categories
age_category: string; // One of 7 age categories
key_information: string; // 1-200 characters
}成功响应：
{
"valid": true,
"data": {
"title": "Koncert Chopina",
"city": "Warszawa",
"event_date": "2025-12-25T19:00:00Z",
"category": "koncerty",
"age_category": "dorosli",
"key_information": "Wieczór muzyki klasycznej"
}
}错误响应：
{
"valid": false,
"errors": {
"title": ["Tytuł jest wymagany"],
"event_date": ["Data wydarzenia nie może być w przeszłości"]
}
}______________________________________________________________________
4. format-event-date
将ISO 8601日期时间转换为YYYY-MM-DD格式。
参数：
{
date: string; // ISO 8601 datetime
}成功响应：
{
"formatted": "2025-12-25",
"original": "2025-12-25T19:00:00Z"
}错误响应：
{
"error": "Invalid date format",
"details": "Expected ISO 8601 string (e.g., 2025-12-25T19:00:00Z)"
}______________________________________________________________________
📦 安装
先决条件
- Node.js：22.14.0或更高
- npm：10.x或更高
- TypeScript：5.7.2（作为开发依赖项安装）
设置
# Clone the repository
git clone https://github.com/Devrilo/CulturAllyAI-MCP-Server.git
cd CulturAllyAI-MCP-Server
# Install dependencies
npm install
# Build the project
npm run build
# Run tests
npm test
# Run tests with coverage
npm test -- --coverage备注：如果您只想在不克隆的情况下使用服务器，可以直接访问生产部署： https://culturallyai-mcp-server.marcin-szwajgier.workers.dev
______________________________________________________________________
🚀 用法
选项1：生产（Cloudflare员工）🌐
使用MCP服务器的最简单方法是通过部署的REST API：
# Get event categories
curl -X POST https://culturallyai-mcp-server.marcin-szwajgier.workers.dev/tools/get-event-categories \
-H "Content-Type: application/json" \
-d '{}'
# Get age categories
curl -X POST https://culturallyai-mcp-server.marcin-szwajgier.workers.dev/tools/get-age-categories \
-H "Content-Type: application/json" \
-d '{}'
# Format event date
curl -X POST https://culturallyai-mcp-server.marcin-szwajgier.workers.dev/tools/format-event-date \
-H "Content-Type: application/json" \
-d '{"date": "2025-12-25T19:00:00Z"}'
# Validate event data
curl -X POST https://culturallyai-mcp-server.marcin-szwajgier.workers.dev/tools/validate-event-data \
-H "Content-Type: application/json" \
-d '{
"title": "Koncert Noworoczny",
"city": "Warszawa",
"event_date": "2025-12-31T20:00:00Z",
"category": "koncerty",
"age_category": "dorosli",
"key_information": "Koncert orkiestry symfonicznej"
}'您还可以在 Cloudflare仪表板:
- 访问https://dash.cloudflare.com
- 首选 工人和页面 → 文化上的mcp服务器
- 点击 编辑代码 （快速编辑）
- 使用HTTP测试接口发送请求
方案2：地方发展（stdio）
# Build the TypeScript code
npm run build
# Run the server (stdio mode)
node dist/index.js选项3：使用MCP检查器
MCP Inspector是一个交互式测试MCP服务器的工具。
# Install MCP Inspector globally (if not already installed)
npm install -g @modelcontextprotocol/inspector
# Run the inspector with your server
npx @modelcontextprotocol/inspector node dist/index.js检查员将在您的浏览器中打开 http://localhost:5173 您可以在哪里：
- 查看可用工具
- 使用自定义参数执行测试工具
- 检查请求/响应有效载荷
- 调试MCP通信
有关详细的测试说明，请参阅 测试.md.
选项4：使用克劳德桌面
添加到您的Claude Desktop配置(claude_desktop_config.json):
{
"mcpServers": {
"culturallyai": {
"command": "node",
"args": ["/absolute/path/to/CulturAllyAI-MCP-Server/dist/index.js"]
}
}
}重新启动Claude Desktop，这些工具将在对话中可用。
______________________________________________________________________
🧪 测试
单元测试
该项目具有全面的单元测试覆盖范围：
# Run all tests
npm test
# Run tests in watch mode
npm test -- --watch
# Run tests with coverage report
npm test -- --coverage测试覆盖率
当前覆盖范围（截至上次运行）：
- 声明：93.65%（阈值：80%）
- 分支：73.91%（阈值：70%）
- 函数：100%（阈值：80%）
- 线条：93.33%（阈值：80%）
测试文件
src/__tests__/categories.test.ts-11类公用设施测试src/__tests__/formatters.test.ts-MCP响应格式的19项测试src/__tests__/date-helpers.test.ts-26项日期实用程序测试src/__tests__/validators.test.ts-30次Zod验证测试src/__tests__/handlers.test.ts-工具操作员的28项测试
总计：114次测试
______________________________________________________________________
💻 发展
脚本
npm run build # Compile TypeScript to dist/
npm test # Run unit tests
npm run lint # Run ESLint
npm run format # Format code with Prettier代码的风格
- TypeScript：严格模式已启用
- ESLint：已配置为TypeScript
- 更漂亮：代码格式
- 进口：使用
.jsES模块的扩展
添加新工具
- 定义工具模式 在
src/tools/definitions.ts
{
name: 'my-new-tool',
description: 'Tool description',
inputSchema: { /* JSON Schema */ }
}- 创建处理程序 在
src/tools/handlers.ts
function handleMyNewTool(args: unknown): McpResponse {
// Implementation
}- 添加到路由器 在
handleToolCall
case 'my-new-tool':
return handleMyNewTool(args);- 编写测试 在
src/__tests__/handlers.test.ts
- 更新文档 在README.md中
______________________________________________________________________
🚢 部署
Cloudflare Workers
此服务器已成功部署并在Cloudflare Workers上运行！
🌐 实时URL: https://culturallyai-mcp-server.marcin-szwajgier.workers.dev
快速部署
# Login to Cloudflare (first time only)
npx wrangler login
# Build and deploy
npm run build
npx wrangler deploy可用端点
部署的服务器为所有MCP工具提供REST API端点：
GET /-API文档和示例GET /health-健康检查端点GET /tools-列出所有具有模式的可用工具POST /tools/get-event-categories-获取事件类别POST /tools/get-age-categories-获取年龄类别POST /tools/validate-event-data-验证事件数据POST /tools/format-event-date-ISO 8601中的日期格式
测试部署
# Health check
curl https://culturallyai-mcp-server.marcin-szwajgier.workers.dev/health
# Get event categories
curl -X POST https://culturallyai-mcp-server.marcin-szwajgier.workers.dev/tools/get-event-categories \
-H "Content-Type: application/json" \
-d '{}'
# Validate event data
curl -X POST https://culturallyai-mcp-server.marcin-szwajgier.workers.dev/tools/validate-event-data \
-H "Content-Type: application/json" \
-d '{
"title": "Koncert",
"city": "Warszawa",
"event_date": "2025-12-25T19:00:00Z",
"category": "koncerty",
"age_category": "dorosli",
"key_information": "Test"
}'监控
访问Cloudflare仪表板以监控您的部署：
- 首选https://dash.cloudflare.com
- 导航至 工人和页面
- 选择 文化上的mcp服务器
- 查看指标、日志和性能数据
有关详细的部署说明，请参阅 部署.md.
地方发展（stdio）
对于使用Claude Desktop或MCP Inspector进行本地MCP开发，请使用stdio传输：
# Run locally
node dist/index.js
# With MCP Inspector
npx @modelcontextprotocol/inspector node dist/index.js架构说明
- 生产（Cloudflare）：使用HTTP/REST API（工作获取处理程序）
- 发展（地方）：使用stdio传输（通过stdin/stdout的MCP协议）
- 两个版本共享相同的工具实现和验证逻辑
环境变量
目前，不需要环境变量（MVP）。未来的版本可能会添加：
- 用于身份验证的API密钥
- 数据库连接字符串
- 功能标志
______________________________________________________________________
📁 项目结构
CulturAllyAI-MCP-Server/
├── src/
│ ├── __tests__/ # Unit tests
│ │ ├── setup.ts
│ │ ├── categories.test.ts
│ │ ├── formatters.test.ts
│ │ ├── date-helpers.test.ts
│ │ ├── validators.test.ts
│ │ └── handlers.test.ts
│ ├── tools/ # MCP tool definitions and handlers
│ │ ├── definitions.ts # Tool schemas (JSON Schema)
│ │ └── handlers.ts # Tool execution logic
│ ├── utils/ # Utility modules
│ │ ├── categories.ts # Static category data
│ │ ├── formatters.ts # MCP response formatting
│ │ ├── date-helpers.ts # Date conversion utilities
│ │ └── validators.ts # Zod validation schemas
│ └── index.ts # Server entry point
├── dist/ # Compiled JavaScript (gitignored)
├── coverage/ # Test coverage reports (gitignored)
├── docs/ # Documentation
│ ├── TESTING.md # Testing guide
│ └── DEPLOYMENT.md # Deployment guide
├── package.json # NPM dependencies and scripts
├── tsconfig.json # TypeScript configuration
├── vitest.config.ts # Vitest test configuration
├── wrangler.toml # Cloudflare Workers config
└── README.md # This file______________________________________________________________________
📚 相关文档
______________________________________________________________________
🤝 贡献
这是一个教育项目。欢迎投稿！
- 分叉存储库
- 创建要素分支(
git checkout -b feature/amazing-feature) - 提交您的更改(
git commit -m 'Add amazing feature') - 推到分支(
git push origin feature/amazing-feature) - 打开拉取请求
______________________________________________________________________
📝 许可证
MIT许可证-有关详细信息，请参阅许可证文件
______________________________________________________________________
👨💻 作者
作为理解模型上下文协议（MCP）架构的学习练习而创建。
相关项目: CulturAllyAI -文化活动管理的主要应用
______________________________________________________________________
🙏 致谢
- 模型上下文协议 -协议规范
- Anthropic -MCP创建者和Claude Desktop
- Cloudflare Workers -部署平台
- 黄道 -TypeScript第一模式验证