Record MCP Server

记录MCP服务器

一种模型上下文协议（MCP）服务器，用于存储和管理具有用户定义模式的动态审查记录。非常适合组织咖啡、威士忌、葡萄酒或你能想到的任何其他类别的评论！

特性

• 动态模式：动态创建带有自定义字段的审核类型
• 灵活存储：本地文件系统（开发）或Cloudflare R2（生产）
• 类型安全：使用TypeScript和运行时验证构建
• 可扩展：向现有审核类型添加新字段
• 轻松迁移：使用一个环境变量从本地存储切换到云存储

快速开始

安装

# Install dependencies
npm install

# Build the project
npm run build

配置

复制示例环境文件：

cp .env.example .env

对于本地开发（默认）：

STORAGE_PROVIDER=local
LOCAL_DATA_PATH=./data

对于Cloudflare R2的生产：

STORAGE_PROVIDER=r2
R2_ACCOUNT_ID=your_account_id
R2_ACCESS_KEY_ID=your_access_key
R2_SECRET_ACCESS_KEY=your_secret_key
R2_BUCKET_NAME=review-records

运行服务器

开发模式（自动重新加载）：

npm run dev

生产方式：

npm run build
npm start

运行测试

npm test

MCP工具

服务器提供以下MCP工具：

1. list_review_types

列出所有审核类型及其模式和记录计数。

参数：无

示例响应:

{
  "types": [
    {
      "name": "coffee",
      "schema": [
        { "name": "flavor", "type": "string" },
        { "name": "aroma", "type": "string" },
        { "name": "acidity", "type": "string" }
      ],
      "recordCount": 5,
      "createdAt": "2025-11-16T10:00:00Z",
      "updatedAt": "2025-11-16T12:00:00Z"
    }
  ]
}

2. get_review_type

获取特定审核类型的详细信息，包括所有记录。

参数:

• typeName （string）：审核类型的名称

示例:

{
  "typeName": "coffee"
}

3. add_review_type

使用自定义架构创建新的审核类型。

参数:

• name （string）：评论类型的名称（例如，“咖啡”、“威士忌”）
• fields （array）：字段定义数组

支持的字段类型:

• string：文本值
• number：数值
• boolean：真/假值
• date：ISO 8601日期字符串

示例:

{
  "name": "coffee",
  "fields": [
    { "name": "flavor", "type": "string" },
    { "name": "aroma", "type": "string" },
    { "name": "acidity", "type": "string" },
    { "name": "rating", "type": "number" }
  ]
}

4. add_field_to_type

将新字段添加到现有审阅类型的架构中。

参数:

• typeName （string）：审核类型的名称
• fieldName （string）：新字段的名称
• fieldType （string）：字段类型（字符串、数字、布尔值、日期）

示例:

{
  "typeName": "coffee",
  "fieldName": "body",
  "fieldType": "string"
}

5. add_review_record

向类型中添加新的审核记录。

参数:

• typeName （string）：审核类型的名称
• data （object）：查看与类型架构匹配的数据

示例:

{
  "typeName": "coffee",
  "data": {
    "flavor": "nutty",
    "aroma": "strong",
    "acidity": "medium",
    "rating": 8.5
  }
}

用法示例

完成工作流程

// 1. Create a new review type
await mcp.callTool("add_review_type", {
  name: "whisky",
  fields: [
    { name: "taste", type: "string" },
    { name: "age", type: "number" },
    { name: "peated", type: "boolean" },
    { name: "tasted_on", type: "date" }
  ]
});

// 2. Add a review
await mcp.callTool("add_review_record", {
  typeName: "whisky",
  data: {
    taste: "smoky and complex",
    age: 12,
    peated: true,
    tasted_on: "2025-11-16T10:00:00Z"
  }
});

// 3. Add more fields later
await mcp.callTool("add_field_to_type", {
  typeName: "whisky",
  fieldName: "region",
  fieldType: "string"
});

// 4. List all types and their data
const result = await mcp.callTool("list_review_types", {});

建筑

项目结构

record-mcp/
├── src/
│   ├── index.ts              # MCP server entry point
│   ├── types.ts              # TypeScript type definitions
│   ├── storage/
│   │   ├── interface.ts      # Storage provider interface
│   │   ├── local.ts          # Local file system storage
│   │   ├── r2.ts             # Cloudflare R2 storage
│   │   └── factory.ts        # Storage provider factory
│   ├── tools/
│   │   ├── list-types.ts     # List and get review types
│   │   ├── add-type.ts       # Create new review type
│   │   ├── add-field.ts      # Add field to type
│   │   └── add-record.ts     # Add review record
│   └── utils/
│       └── validation.ts     # Schema and data validation
├── data/                     # Local storage (when using local provider)
│   ├── types/
│   │   ├── coffee.json
│   │   └── whisky.json
│   └── index.json
└── tests/
    ├── storage.test.ts       # Storage provider tests
    └── tools.test.ts         # MCP tools tests

存储抽象

服务器使用存储抽象层，允许在本地文件和Cloudflare R2之间轻松切换：

• 本地存储 （开发）：使用Node.js fs/promises 存储JSON文件
• R2存储 （生产）：使用AWS S3-兼容的API存储在Cloudflare R2中

两个提供者都实现了相同的功能 StorageProvider 界面，使迁移无缝。

数据格式

每种评论类型都存储为单独的JSON文件：

{
  "name": "coffee",
  "schema": [
    { "name": "flavor", "type": "string" },
    { "name": "aroma", "type": "string" }
  ],
  "records": [
    {
      "id": "1234567890-abc123",
      "data": {
        "flavor": "nutty",
        "aroma": "strong"
      },
      "createdAt": "2025-11-16T10:00:00Z"
    }
  ],
  "createdAt": "2025-11-15T09:00:00Z",
  "updatedAt": "2025-11-16T10:00:00Z"
}

从本地迁移到R2

当您准备投入生产时：

1. 设置Cloudflare R2存储桶
2. 更新您的 .env 带有R2凭据的文件
3. 改变 STORAGE_PROVIDER=r2
4. 重新启动服务器

可选：使用迁移脚本复制现有数据：

// Copy all local files to R2
const localStorage = new LocalStorageProvider('./data');
const r2Storage = new R2StorageProvider(r2Config);

const types = await localStorage.listTypes();
for (const typeName of types) {
  const data = await localStorage.readType(typeName);
  await r2Storage.writeType(typeName, data);
}

验证

服务器提供全面的验证：

• 类型名称：仅限字母数字、连字符和下划线
• 字段类型：必须是以下之一：字符串、数字、布尔值、日期
• 必填字段：记录中必须存在所有架构字段
• 额外字段：记录中不能有不在架构中的字段
• 类型检查：字段值必须与其声明的类型匹配

错误处理

所有工具都返回结构化错误消息：

{
  "error": "Review type \"coffee\" already exists"
}

常见错误：

• 重复的类型名称
• 重复的字段名
• 记录中缺少必填字段
• 类型不匹配
• 类型/字段名无效

发展

建筑

npm run build

观察变化

npm run watch

测试

运行所有测试：

npm test

运行特定测试文件：

tsx tests/storage.test.ts
tsx tests/tools.test.ts

许可证

麻省理工学院

贡献

欢迎投稿！请确保在提交PR之前通过测试。

支持

对于问题或疑问，请打开GitHub问题。