使用说明
MCP数据目录
一种模型上下文协议（MCP）服务器，为AI助手提供对CSV文件中表格数据集的结构化访问。通过干净、类型安全的界面查询、过滤和检索数据。
功能（MVP）
✅ 4个MCP工具
list_datasets-列出所有可用数据集describe_dataset-获取架构和字段信息query_dataset-使用过滤器、投影和限制进行查询get_by_id-按查找键检索特定行
✅ 类型安全架构
- 字符串、数字、布尔值和枚举字段类型
- 现场验证和类型检查
- 所需的现场执行
✅ 过滤（MVP）
eq（等于）contains（不区分大小写的子字符串）and（多种条件）
✅ 智能限制
- 每个数据集的行限制
- 截断指示器
- 可配置的默认值
✅ 热重新加载
- 配置更改会自动应用（1-3ms）
- 无需重新启动服务器
- 安全地拒绝无效的配置
✅ 稳定MVP
- 六边形架构
- 全面的测试覆盖率
- 类型安全实施
- 生产质量错误处理
快速开始
1.安装
npm install
npm run build
2.配置
复制示例配置：
cp examples/config/typical.json config/datasets.json
或者创建自己的：
{
"datasets": [
{
"id": "users",
"name": "User Directory",
"schema": {
"fields": [
{ "name": "id", "type": "number", "required": true },
{ "name": "name", "type": "string", "required": true },
{ "name": "email", "type": "string", "required": true },
{ "name": "role", "type": "enum", "values": ["admin", "user", "guest"] }
],
"visibleFields": ["id", "name", "email", "role"]
},
"source": {
"type": "csv",
"path": "./data/users.csv"
},
"lookupKey": "id",
"limits": {
"maxRows": 100,
"defaultRows": 20
}
}
]
}
3.跑步
npm run dev
服务器在stdio上启动，并公开4个MCP工具。
用法
MCP客户端配置
添加到您的MCP客户端配置中（例如，Claude Desktop）：
{
"mcpServers": {
"catalog": {
"command": "node",
"args": ["/path/to/catalog-mcp/dist/index.js"],
"env": {
"CONFIG_PATH": "/path/to/config/datasets.json"
}
}
}
}
注： 替换
/path/to/...使用您的实际本地文件路径。MCP服务器作为Node.js进程运行，并读取CONFIG_PATH启动时的环境变量。
可用工具
1.列表_数据集
列出所有已配置的数据集。
请求：
{
"tool": "list_datasets"
}
答复：
{
"datasets": [
{
"id": "users",
"name": "User Directory"
},
{
"id": "products",
"name": "Product Catalog"
}
]
}
2.描述数据集
获取数据集的详细架构信息。
请求：
{
"tool": "describe_dataset",
"arguments": {
"datasetId": "users"
}
}
答复：
{
"id": "users",
"name": "User Directory",
"fields": [
{
"name": "id",
"type": "number",
"required": true
},
{
"name": "name",
"type": "string",
"required": true
},
{
"name": "role",
"type": "enum",
"values": ["admin", "user", "guest"]
}
],
"lookupKey": "id",
"limits": {
"maxRows": 100,
"defaultRows": 20
}
}
3.查询数据集
使用可选过滤器、字段投影和限制查询数据集。
简单查询：
{
"tool": "query_dataset",
"arguments": {
"datasetId": "users",
"limit": 10
}
}
使用过滤器：
{
"tool": "query_dataset",
"arguments": {
"datasetId": "users",
"filters": {
"field": "role",
"op": "eq",
"value": "admin"
},
"limit": 10
}
}
使用多个过滤器：
{
"tool": "query_dataset",
"arguments": {
"datasetId": "users",
"filters": {
"and": [
{ "field": "role", "op": "eq", "value": "admin" },
{ "field": "name", "op": "contains", "value": "smith" }
]
}
}
}
使用现场投影：
{
"tool": "query_dataset",
"arguments": {
"datasetId": "users",
"fields": ["id", "name"],
"limit": 10
}
}
答复：
{
"rows": [
{ "id": 1, "name": "Alice Smith", "email": "alice@example.com", "role": "admin" },
{ "id": 6, "name": "Frank Miller", "email": "frank@example.com", "role": "admin" }
],
"fields": ["id", "name", "email", "role"],
"rowsReturned": 2,
"totalRows": 2,
"truncated": false
}
4.获取_ _ id
按查找键检索单行。
请求：
{
"tool": "get_by_id",
"arguments": {
"datasetId": "users",
"id": "1"
}
}
答复：
{
"row": {
"id": 1,
"name": "Alice Smith",
"email": "alice@example.com",
"role": "admin"
}
}
如果未找到：
{
"row": null
}
过滤器操作员
MVP支持三个运算符：
eq（等于）
完全匹配（字符串区分大小写）。
{
"field": "role",
"op": "eq",
"value": "admin"
}
包含（子字符串）
不区分大小写的子字符串搜索。
{
"field": "name",
"op": "contains",
"value": "smith"
}
和（连词）
所有条件都必须为真。
{
"and": [
{ "field": "role", "op": "eq", "value": "admin" },
{ "field": "active", "op": "eq", "value": true }
]
}
筛选器架构
所有过滤器表达式都遵循以下规范的JSON结构：
简单过滤器：
{
"field": "fieldName",
"op": "eq" | "contains",
"value": any
}
复合过滤器（和）：
{
"and": [
{ "field": "...", "op": "...", "value": ... },
{ "field": "...", "op": "...", "value": ... }
]
}
MVP后： 其他运营商即将到来(ne, gt, gte, lt, lte, in, or)使用相同的结构。
配置
数据集结构
{
"datasets": [
{
"id": "string", // Unique identifier
"name": "string", // Display name
"schema": {
"fields": [ // Field definitions
{
"name": "string", // Field name (matches CSV header)
"type": "string", // string | number | boolean | enum
"required": boolean, // Optional, default: false
"values": ["..."] // Required for enum type
}
],
"visibleFields": ["..."] // Fields accessible in queries
},
"source": {
"type": "csv", // Only CSV in MVP
"path": "string" // Relative path to CSV file
},
"lookupKey": "string", // Optional, field name for get_by_id
"limits": {
"maxRows": number, // Hard limit
"defaultRows": number // Default when not specified
}
}
]
}
字段类型
| 类型 | 描述 | 示例值 |
|---|---|---|
string |
文本数据 | "Alice", "alice@example.com" |
number |
数字数据 | 42, 99.99, -5 |
boolean |
正确/错误 | true, false |
enum |
预定义值 | "admin" （必须在 values 阵列） |
配置格式
配置用途 JSON 格式。这是MVP的主要和推荐格式。
注： 在未来的版本中可能会添加对YAML的支持，但JSON仍然是规范格式。
配置验证
服务器在启动时验证配置并拒绝无效的配置：
✅ 已执行的检查：
- 所有必填字段均已显示
- 字段类型有效
- 枚举字段不为空
values数组 visibleFields引用现有字段lookupKey引用现有字段- 数据集ID是唯一的
- 限制有效（正，maxRows≥defaultRows）
- CSV文件存在并且可读
快速失败： 无效的配置会阻止服务器启动，并显示明确的错误消息。
CSV文件格式
需求
- 标题行 列名称（第一行）
- 列名 必须与字段定义匹配（区分大小写）
- 数据类型 必须与字段类型匹配
- UTF-8编码
- 标准CSV格式 （逗号分隔）
示例
id,name,email,role,active
1,Alice Smith,alice@example.com,admin,true
2,Bob Johnson,bob@example.com,user,true
3,Charlie Brown,charlie@example.com,guest,false
类型格式
布尔值： 必须是 true 或 false （小写）
active
true
false
编号： 整数或小数
price,quantity
99.99,5
149.99,10
枚举： 必须与配置的值之一匹配
role
admin
user
guest
热重新加载
配置更改会自动检测到：
- 编辑
config/datasets.json - 保存文件
- 更改将在1-3ms内生效（仅限目录交换）
- 无效更改被拒绝（保持当前配置）
查看日志：
[INFO] Config reloaded successfully in 2ms
它是如何工作的：
- 监视配置文件是否有更改
- 更改时：验证新配置
- 如果有效：原子交换到新目录
- 如果无效：保留当前状态，记录错误
无需重新启动服务器！
人工智能使用指南
此服务器针对以下方面进行了优化 对CSV支持的参考数据的本地、模式感知访问 –我用于项目设计、探索、文档聚合和爱好系统的数据类型。对于高容量或关键任务的生产工作负载，您通常会将LLM与专用的数据库支持的MCP服务器配对，并使此目录专注于代理附近的轻量级、结构化数据集。
设计数据集时：
人工智能数据集设计
保持数据集集中：
- 小型单用途桌子比大型多用途桌子效果更好
- 将参考数据（ID、名称、代码）与描述性内容分开
- 将复杂的领域分解为多个相关的数据集
优化代币效率：
- 使用
visibleFields仅显示必要的列 - 保持字段名称简短但有意义
- 在过滤时，更喜欢ID和代码而不是长文本字段
稳定查询设计：
- 使用一致、稳定的标识符（数字ID、SKU、代码）
- 避免依赖自由文本名称作为查找关键字
- 规范化分类数据（使用枚举，而不是自由文本）
过滤结构：
- 基于标记的字段支持灵活的查询(
status,category,type) - 为受控词汇表使用枚举
- 常用过滤器的布尔标志(
active,published,available)
示例模式：
- 索引数据集： ID、名称、标签、状态（小，经常查询）
- 详细数据集： 所有字段的完整记录（按ID查询）
- 参考数据集： 查找表、枚举、测量量表（小、稳定）
建筑
该项目如下 六边形体系结构 为了清晰地分离关注点：
┌─────────────────────────────────────────────────────┐
│ Primary Adapters (MCP) │
│ ↓ │
│ Primary Ports (Tools) │
│ ↓ │
│ Use Cases (Business Logic) │
│ ↓ │
│ Domain Layer (Pure Logic) │
│ ↓ │
│ Secondary Ports (Storage) │
│ ↓ │
│ Secondary Adapters (CSV, Config) │
└─────────────────────────────────────────────────────┘
关键原则：
- 域层没有外部依赖关系
- 依赖关系指向内部（适配器→ 域）
- 业务逻辑是孤立的，可测试的
- 易于使用新适配器进行扩展
看 docs/dev/mcp数据目录.md 获取详细的架构文档。
例子
这 examples/ 目录包含：
配置
minimal.json-单个数据集，基本特征typical.json-多个数据集，常见模式advanced.json-具有许多功能的复杂场景
数据集
minimal.csv-5行，2列sample-users.csv-10个具有角色的用户sample-products.csv-15产品分类employees.csv-15名部门员工inventory.csv-20个库存项目orders.csv-20客户订单
试试看：
cp examples/config/typical.json config/datasets.json
npm run dev
看 示例/README.md 详细文档。
发展
设置
npm install
npm run build
以开发模式运行
npm run dev
运行测试
# All tests
npm test
# With coverage
npm run test:coverage
# Watch mode
npm run test:watch
为生产而建
npm run build
输出在 dist/ 目录。
测试
测试覆盖范围：
- 全面的测试套件，覆盖率高
- 领域逻辑和用例的单元测试
- MCP工具和热重载的集成测试
- 跟踪报表和分支机构的覆盖范围
测试结构：
test/
├── unit/
│ ├── domain/ # Domain services and value objects
│ └── use-cases/ # Use case orchestration
└── integration/
├── mcp-tools.test.ts # All 4 MCP tools
├── config-hot-reload.test.ts # Hot reload behavior
├── csv-hot-visibility.test.ts # Visible fields
└── limits-and-truncation.test.ts # Row limits
演出
特点：
- 配置重新加载：1-3ms（仅目录交换）
- CSV加载：每个文件5-10ms（因大小而异）
- 查询执行：内存操作1-2ms
- 内存：O（n），其中n=数据集大小
CSV加载行为：
- 读取CSV文件 按需 对于每个查询
- CSV数据无内存缓存
- 这使内存使用率保持较低水平，但在查询延迟中包括文件I/O
- 配置目录已缓存；每次查询只加载CSV数据
可扩展性：
- 适用于最多约100K行的数据集
- 查询延迟包括文件读取时间（每个CSV约5-10ms）
- 对于高性能或大型数据集，使用数据库后端（MVP后）
- 考虑数据集设计：多个小型CSV比一个大型CSV更好
路线图
✅ MVP完成（全部6个阶段）
- [x] 六边形架构
- [x] 4个MCP工具（列表、描述、查询、get_by_id）
- [x] MVP过滤器运算符（eq、contains和）
- [x] 类型验证（字符串、数字、布尔值、枚举）
- [x] 热重载支持
- [x] 全面的测试覆盖率
- [x] 错误处理和日志记录
- [x] 完整的文档（README、开发指南、示例）
🚀 发布MVP功能
- []其他筛选运算符（ne、gt、gte、lt、lte、in或）
- []排序（按顺序）
- []复杂类型（数组、嵌套对象）
- []多个数据源（PostgreSQL、SQLite、JSON）
- []聚合（COUNT、SUM、AVG等）
- []全文搜索
- []性能缓存层
- []GraphQL风格的查询语言
看 docs/project plans/project-plan-v1.final.md 了解详情。
文档
贡献
欢迎投稿！该项目如下：
- 六边形架构 -保持域名纯净
- 测试驱动开发 -先写测试
- 类型安全性 -利用TypeScript
- 清洁代码 -遵循现有模式
看 .clinerules/core-rules.md 建筑指南。
故障排除
服务器无法启动
检查配置：
node dist/index.js
# Look for validation errors in output
常见问题：
- CSV文件路径不正确
- 字段类型不匹配
- 缺少必填字段
- 重复的数据集ID
查询未返回任何结果
验证数据集：
{
"tool": "describe_dataset",
"arguments": { "datasetId": "your-dataset" }
}
检查：
- 数据集ID正确
- CSV文件有数据
- 筛选器匹配字段类型
- 字段名称位于
visibleFields
热重载不工作
验证文件监视：
- 配置文件路径正确
- 文件系统权限允许读取
- 检查服务器日志以确认重新加载
许可证
麻省理工学院
鸣谢
内置：
- TypeScript
- 模型上下文协议SDK
- 萨德 -架构验证
- 乔基达尔 -文件监视
- 测试 -测试
项目状态
版本： 1.0.0-mvp
状态： 稳定MVP
最后更新时间： 2025-11-30
注： 徽章上的测试和性能数字反映了发布时的状态。专为生产风格的工作负载而设计，但要验证性能并适合您的特定环境。
所有6个阶段均已完成：
- ✅ 第1阶段：骨架和配置
- ✅ 第二阶段：核心用例
- ✅ 阶段3：热重新加载
- ✅ 第4阶段：MCP适配器
- ✅ 第5阶段：硬化和测试
- ✅ 第6阶段：文件编制
