Socrata MCP服务器v2.0.0
遵循以代理为中心的设计最佳实践的高质量模型上下文协议（MCP）服务器。提供与Socrata开放数据API交互的全面工具。
✨ 以代理为中心的设计
按照MCP最佳实践构建 以工作流为中心的工具 按领域组织，以实现最佳代理可用性：
- 基于工作流的工具设计 -工具整合相关操作以完成任务
- 优化上下文使用 -管理令牌使用的简洁与详细响应选项
- 可操作的错误消息 -为代理商提供如何解决问题的明确指导
- 自然任务组织 -按逻辑工作流域分组的工具
- 综合注释 -用于优化代理交互的完整MCP工具元数据
🛠️ 工具收藏
此MCP服务器包括 12个综合工具 组织起来 6个领域:
目录和搜索工具
- socrata_get_catalog -获取按类别和类型筛选的域目录
- socrata_search_catalog -具有多个过滤器、排序和分页的高级目录搜索
- socrata_search_users -使用ID、电子邮件、角色和状态过滤器搜索用户
- socrata_search_teams -使用各种过滤器搜索团队
资产管理工具
- socrata_get_元数据 -通过4x4标识符获取特定资产的元数据
- socrata_update_元数据 -更新资产元数据（名称、描述、标签等）
权限管理
- 苏格拉底获取许可 -获取资产的当前权限
- socrata_update_permissions -更新资产权限（范围和用户访问级别）
发布和日程安排
- socrata_get_schedule -获取数据集的发布时间表和节奏信息
活动和审计
- socrata_get_active_log -获取活动日志，过滤日期范围和活动类型
用户和角色管理
- socrata_get_user_roles -获取分配给特定用户的角色
- socrata_update_user_roles -更新特定用户的角色
工作流管理
- socrata_get_workflow_context -获取工作流上下文信息
- socrata_update_workflow_context -更新工作流上下文
安装
- 克隆此存储库
- 安装依赖项：
npm install- 构建服务器：
npm run build配置
设置以下环境变量：
SOCRATA_DOMAIN-允许的Socrata域的逗号分隔列表（可选，空表示允许所有域）SOCRATA_ID-用于身份验证的Socrata应用程序ID（可选）SOCRATA_SECRET-用于身份验证的Socrata应用程序密钥（可选）
用法
运行服务器
npm run start服务器监听stdio传输并遵循MCP协议规范。
Claude桌面配置示例
将此添加到您的Claude Desktop配置中：
{
"mcpServers": {
"socrata": {
"command": "node",
"args": ["/path/to/socrata-mcp-server/dist/index.js"],
"env": {
"SOCRATA_DOMAIN": "data.cityofchicago.org,data.seattle.gov",
"SOCRATA_ID": "your_app_id",
"SOCRATA_SECRET": "your_app_secret"
}
}
}
}工具特性
所有工具包括：
- 输入验证 使用Zod模式
- 灵活的响应格式 （JSON或Markdown）
- 细节级别 （简明或详细）
- 全面的错误处理
- 域确认 以及身份验证
- 分页支持 在适用的情况下
- 字符限制 对于大响应进行截断
API覆盖范围
该服务器涵盖了主要的Socrata API端点：
- 目录API v1（搜索、筛选、元数据）
- 资产API（权限、元数据更新）
- 发布API v1（时间表和节奏）
- 用户和团队API（搜索和管理）
- 活动日志API（审核跟踪）
- 工作流API（上下文管理）
安全
- 域分配以限制对特定Socrata实例的访问
- 使用应用程序ID和密钥进行安全身份验证
- 所有参数的输入验证
- 不暴露敏感信息的错误处理
发展
服务器由以下组件构建：
- TypeScript 用于类型安全
- MCP TypeScript SDK 符合协议
- 萨德 用于运行时模式验证
- Node.js 20+ 了解现代JavaScript功能
项目结构
src/
├── index.ts # Main server with domain-organized tool registration
├── utils/
│ └── socrata-utils.ts # Common utilities and API helpers
└── tools/ # Domain-specific tool collections
├── catalog-tools.ts # Dataset discovery and search
├── user-tools.ts # User and team management
├── asset-tools.ts # Asset metadata and permissions
├── publishing-tools.ts # Publishing schedules and automation
├── activity-tools.ts # Activity logs and audit trails
└── workflow-tools.ts # Workflow context management🏗️ 建筑亮点
领域组织结构
- 逻辑分组：按工作流域而非API结构组织的工具
- 可维护代码：每个域都放在单独的文件中，便于维护
- 可发现的工具：为代理的可发现性提供一致的命名和分组
MCP最佳实践实施
- 工具注释：完整的元数据
readOnlyHint,destructiveHint,idempotentHint,openWorldHint - 工作流焦点：为完成任务而设计的工具，而不仅仅是API端点包装
- 代理商友好：错误消息指导代理正确使用模式
- 上下文优化：灵活的响应格式和详细程度
质量保证
- TypeScript严格模式：全类型安全和编译时错误检查
- Zod模式验证：带有描述性错误消息的运行时输入验证
- 全面的错误处理：具有可操作指导的优雅故障模式
- 生产就绪：适当的生命周期管理和优雅的关机处理