DataSF MCP Server

DataSF MCP 服务器

模型上下文协议（MCP）服务器，为LLM提供对旧金山开放数据门户（DataSF）的无缝访问，由Socrata平台提供支持。

概述

该MCP服务器使Claude等人工智能助手能够通过简单、标准化的界面搜索、探索和查询旧金山的公共数据集。它处理了Socrata API的复杂性，提供了智能列名更正，并包括模式缓存以获得最佳性能。

主要特点

• 🔍 数据集搜索和发现 -按关键字查找数据集或按类别浏览
• 📊 模式检索 -查询前获取列名和数据类型
• 💬 SoQL查询执行 -对任何数据集运行类似SQL的查询
• 🎯 模糊列匹配 -自动更正列名中的拼写错误
• ⚡ 架构缓存 -通过智能缓存减少API调用
• 🔐 可选身份验证 -支持Socrata应用代币以获得更高的利率限制
• ✅ 基于属性的测试 -全面的正确性保证

可用工具

1. search_datasf

按关键字搜索数据集。

参数：

• query （字符串，必填）：搜索关键字（1-500个字符）
• limit （数字，可选）：最大结果（默认值：5，最大值：20）

例子：

Search for police incident datasets

2. list_datasf

浏览可用数据集，可选择按类别过滤。

参数：

• category （字符串，可选）：按类别筛选
• limit （数字，可选）：最大结果（默认值：5，最大值：20）

例子：

List recent public safety datasets

3. get_schema

获取特定数据集的架构（列和数据类型）。

参数：

• dataset_id （字符串，必填）：数据集4x4 ID（格式： xxxx-xxxx)

例子：

Get the schema for dataset wg3w-h783

4. query_datasf

对数据集执行SoQL（Socrata查询语言）查询。

参数：

• dataset_id （字符串，必填）：数据集4x4 ID
• soql （字符串，必填）：SoQL查询（1-4000个字符）
• auto_correct （布尔值，可选）：启用列名更正（默认值：true）

例子：

Query dataset wg3w-h783: SELECT incident_category, COUNT(*) GROUP BY incident_category LIMIT 10

安装

先决条件

• Node.js 18或更高版本
• npm或纱线

本地设置（可选）

如果要在本地运行或修改服务器：

1. 克隆存储库：

git clone https://github.com/fwextensions/datasf-mcp.git
cd datasf-mcp

1. 安装依赖项：

npm install

1. 运行服务器：

npm start

服务器使用 tsx 直接运行TypeScript而不需要构建步骤。

用法

MCP检验员测试

对于MCP检查器，您需要使用本地安装：

# First, clone and install locally
git clone https://github.com/fwextensions/datasf-mcp.git
cd datasf-mcp
npm install

# Then run the inspector
npx -y @modelcontextprotocol/inspector tsx src/index.ts

在检查器UI中，使用：

• 命令： tsx
• 论据： src/index.ts （如果从目录外部运行，则为绝对路径）

npx快速入门（推荐）

使用服务器最简单的方法是直接从GitHub使用npx：

{
  "mcpServers": {
    "datasf": {
      "command": "npx",
      "args": ["-y", "github:fwextensions/datasf-mcp"],
      "env": {
        "SOCRATA_APP_TOKEN": "your-optional-token"
      }
    }
  }
}

这将自动从GitHub下载并运行最新版本，无需任何手动安装。

本地安装

或者，克隆并在本地安装：

git clone https://github.com/fwextensions/datasf-mcp.git
cd datasf-mcp
npm install

然后在MCP配置中使用绝对路径（见下文）。

Claude桌面配置

添加到您的Claude Desktop配置文件中：

窗户： %APPDATA%\Claude\claude_desktop_config.json\ macOS： ~/Library/Application Support/Claude/claude_desktop_config.json\ Linux： ~/.config/Claude/claude_desktop_config.json

选项1：使用npx（推荐）

{
  "mcpServers": {
    "datasf": {
      "command": "npx",
      "args": ["-y", "github:fwextensions/datasf-mcp"],
      "env": {
        "SOCRATA_APP_TOKEN": "your-optional-token"
      }
    }
  }
}

选项2：使用本地安装

{
  "mcpServers": {
    "datasf": {
      "command": "npx",
      "args": ["tsx", "/absolute/path/to/datasf-mcp/src/index.ts"],
      "env": {
        "SOCRATA_APP_TOKEN": "your-optional-token"
      }
    }
  }
}

重要提示： 替换 /absolute/path/to/datasf-mcp 包含克隆此项目的实际完整路径。

Kiro IDE的配置

创建或编辑 .kiro/settings/mcp.json:

选项1：使用GitHub上的npx（推荐）

{
  "mcpServers": {
    "datasf": {
      "command": "npx",
      "args": ["-y", "github:fwextensions/datasf-mcp"],
      "env": {
        "SOCRATA_APP_TOKEN": "your-optional-token"
      },
      "disabled": false,
      "autoApprove": []
    }
  }
}

选项2：使用本地安装

{
  "mcpServers": {
    "datasf": {
      "command": "npx",
      "args": ["tsx", "src/index.ts"],
      "env": {
        "SOCRATA_APP_TOKEN": "your-optional-token"
      },
      "disabled": false,
      "autoApprove": []
    }
  }
}

获取Socrata应用代币

服务器无需对公共数据进行身份验证即可工作，但应用令牌会增加速率限制：

1. 访问https://data.sfgov.org/
2. 注册一个免费帐户
3. 导航到开发人员设置
4. 创建新的应用令牌
5. 将其添加到MCP配置中

发展

项目结构

datasf-mcp-server/
├── src/
│   ├── index.ts              # MCP server entry point
│   ├── socrataClient.ts      # Socrata API client
│   ├── validator.ts          # Input validation with Zod
│   ├── fuzzyMatcher.ts       # Column name auto-correction
│   ├── cache.ts              # Schema caching
│   ├── errorHandler.ts       # Error handling utilities
│   └── __tests__/
│       └── property/         # Property-based tests
├── dist/                     # Compiled JavaScript output
├── package.json
└── tsconfig.json

可用脚本

• npm run build -将TypeScript编译为JavaScript
• npm start -运行已编译的服务器
• npm test -运行所有测试
• npm run test:watch -在监视模式下运行测试

运行测试

npm test

该项目使用基于属性的测试 fast-check 以确保在广泛的输入范围内的正确性。

建筑

服务器采用模块化架构：

1. MCP服务器 -通过stdio处理协议通信
2. Socrata客户 -管理对Socrata API的HTTP请求
3. 验证器 -使用Zod模式验证所有输入
4. 模糊匹配器 -使用Fuse.js更正列名拼写错误
5. 架构缓存 -在内存中缓存数据集模式（5分钟TTL）
6. 错误处理器 -对LLM消费的错误进行分类和格式化

查询示例

在LLM中配置后，您可以提出以下问题：

• “搜索关于旧金山住房的数据集”
• “警察事件数据集（wg3w-h783）的模式是什么？”
• “向我展示警方事件数据集中排名前10的事件类别”
• “查找2024年颁发的所有建筑许可证”
• “关于交通，有哪些可用的数据集？”

使用的API端点

服务器与三个Socrata API交互：

• 发现API: https://api.us.socrata.com/api/catalog/v1 -数据集搜索和浏览
• 视图API: https://data.sfgov.org/api/views/{id}.json -模式检索
• 资源API: https://data.sfgov.org/resource/{id}.json -数据查询

错误处理

服务器为以下内容提供描述性错误消息：

• 验证错误 -输入格式或长度无效
• 未找到 -数据集不存在
• 速率限制 -请求太多（添加应用令牌以解决）
• 超时 -请求超过30秒
• API错误 -Socrata特定错误（例如SoQL语法错误）

贡献

欢迎投稿！该项目使用：

• TypeScript用于类型安全
• Zod用于运行时验证
• 基于属性的测试的快速检查
• Vitest作为测试跑者

许可证

麻省理工学院

资源

• Datasf门户
• API文件
• SoQL查询语言
• 模型上下文协议

故障排除

服务器未启动

• 确保你跑了 npm run build 第一
• 检查是否安装了Node.js 18+

LLM中未显示工具

• 验证配置中的路径是否为绝对路径
• 添加配置后重新启动LLM应用程序
• 检查LLM日志中的连接错误

速率限制错误

• 将Socrata应用令牌添加到您的配置中
• 减少请求的频率

查询中的列名错误

• 使用 get_schema 首先看到有效的列名
• 启用 auto_correct: true （默认）用于自动纠正拼写错误