MCP JSON Cache

MCP JSON 缓存服务器

一个高性能的MCP（模型上下文协议）服务器，它在内存中缓存JSON文件，以便快速进行基于键的查找。该服务器专为遗留系统分析和重复的JSON数据访问模式而设计。

特点/特性

• ⚡（闪电符号，常用于表示快速、能量、电力等概念） 快速内存内缓存键查找的毫秒级响应时间
• 🔑 翻译为中文是：钥匙 嵌套键访问支持点表示法（user.profile.name）
• 📁 代表文件夹的符号，可译为“文件夹”或“文件夹图标”。 多源支持同时缓存多个JSON文件
• 🔄 翻译成中文是：🔄（这个符号本身在中文中没有特定含义，通常表示循环、重复或刷新，具体翻译可能根据上下文有所不同，但直接翻译该符号仍为“🔄”） 自动重载文件更改时自动刷新缓存
• 🌐（表示互联网或全球网络的符号，无直接对应中文翻译，可理解为“网络”或“互联网”的意象） 网页管理界面内置仪表板，用于监控和管理
• 🛡️ 译为中文是“盾牌”。这个符号通常用来表示保护、防御或防御性的屏障。 容错性失败的源不会影响其他缓存数据
• 📊（表格） 统计性能指标和缓存命中跟踪

快速入门

1. 安装

git clone 
cd mcp-json-cache
npm install

2. 构建

npm run build

3. 基本用法

# Create a test JSON file
echo {"test": "value", "foo": "bar"} > test.json

# Set environment variable and run
set JSON_FILE=test.json
npm start

4. 通过Web界面访问

打开您的浏览器并导航至：

http://localhost:6315

安装与设置

先决条件

• Node.js 16及以上版本
• npm 或 yarn

开发环境设置

# Clone repository
git clone 
cd mcp-json-cache

# Install dependencies
npm install

# Development mode (with TypeScript)
npm run dev

# Watch mode (auto-recompile on changes)
npm run watch

生产构建

# Compile TypeScript to JavaScript
npm run build

# Run the compiled version
npm start

配置

环境变量

使用环境变量进行配置（按优先级顺序）：

单个JSON文件

set JSON_FILE=./path/to/your/file.json

多个JSON文件（自动命名）

set JSON_FILES=./queries.json;./procedures.json;./codes.json

多个指定来源（推荐）

set JSON_SOURCES=queries:C:/data/queries.json;procedures:C:/data/procedures.json;codes:C:/data/codes.json

Web服务器选项

# Disable web server
set WEB_ENABLED=false

# Change port (default: 6315, auto-tries next port if busy)
set WEB_PORT=3000

# Change host (default: localhost)
set WEB_HOST=0.0.0.0

# Log level (debug, info, warn, error)
set LOG_LEVEL=info

配置文件

创建 config/default.json 对于持久配置：

{
  "sources": {
    "queries": {
      "path": "./data/queries.json",
      "watch": true,
      "primary": true
    },
    "procedures": {
      "path": "./data/procedures.json",
      "watch": true,
      "primary": false
    }
  },
  "options": {
    "autoReload": true,
    "cacheSize": 1000,
    "logLevel": "info"
  },
  "web": {
    "enabled": true,
    "port": 6315,
    "host": "localhost"
  }
}

使用示例

示例1：遗留数据库分析

# Setup for legacy system analysis
set JSON_SOURCES=queries:C:/legacy/complete_query_index.json;procedures:C:/legacy/aps_procedure.json;codes:C:/legacy/error_codes.json
npm start

示例2：多环境配置

{
  "sources": {
    "dev_queries": {
      "path": "./data/dev/queries.json",
      "watch": true,
      "primary": true
    },
    "prod_queries": {
      "path": "./data/prod/queries.json",
      "watch": false,
      "primary": false
    },
    "error_codes": {
      "path": "./data/error_codes.json",
      "watch": true
    }
  }
}

示例3：开发环境设置

# For development with hot reload
set JSON_SOURCES=test_data:./test-data/sample.json
set LOG_LEVEL=debug
set WEB_PORT=3000
npm run dev

MCP 工具

query_json

通过键查询缓存的JSON数据，可选地指定数据来源。

参数：

• key （必需）：用于查找的键，支持点号表示法进行嵌套访问
• source （可选）：特定的JSON源名称

示例：

// Basic lookup
await query_json({ key: "user.name" })

// From specific source
await query_json({ key: "procedure.get_user", source: "procedures" })

// Nested access
await query_json({ key: "database.connection.pool.max_connections" })

list_json_keys

列出缓存JSON源中的可用键。

参数：

• source （可选）：过滤到特定源
• prefix （可选）：按前缀过滤键

示例：

// List all keys
await list_json_keys()

// Keys from specific source
await list_json_keys({ source: "queries" })

// Keys with prefix
await list_json_keys({ prefix: "user." })

list_sources

显示所有已加载的JSON源及其统计数据。

返回： 源元数据数组，包括：

• 源文件名和文件路径
• 密钥数量和文件大小
• 加载时间和点击次数
• 手表状态

网络管理用户界面

访问网页界面于 http://localhost:6315

仪表盘选项卡

• 总体统计总资源数、密钥数、内存使用量、缓存命中率
• 源卡带重载控制的单个源状态
• 快速操作重新加载所有资源，清除缓存，查看日志

“Sources”选项卡

• 源选择器在不同的JSON源之间切换
• 关键词搜索按名称或前缀查找密钥
• 结果表带搜索功能的分页密钥列表
• 值查看器点击任意键以在模态框中查看其 JSON 值

日志选项卡

• 实时日志服务器日志的WebSocket流式传输
• 日志过滤按级别过滤（调试、信息、警告、错误）
• 自动滚动自动追踪新日志
• 清除日志清除日志显示

与Claude代码的集成

添加到您的 .claude/settings.local.json：

{
  "mcpServers": {
    "json-cache": {
      "command": "node",
      "args": ["C:/project/mcp-json-cache/dist/index.js"],
      "env": {
        "JSON_SOURCES": "queries:C:/path/to/queries.json;procedures:C:/path/to/procedures.json"
      }
    }
  }
}

验证步骤

1. 构建项目：

   npm run build

1. 重启Claude代码 加载MCP服务器

1. 验证连接：

- 使用 list_sources 在Claude代码中的工具 - 检查您的JSON源是否已列出 - 与……一起测试 query_json 确认数据访问权限

建筑学

组件概览

┌─────────────────┐
│  Claude Code    │ (MCP client via stdio)
└────────┬────────┘
         │ MCP Protocol
┌────────▼────────┐
│  MCP Server     │ (stdio transport)
└────────┬────────┘
         │
┌────────▼──────────┐
│  CacheManager     │ (Coordinates multiple sources)
└────────┬──────────┘
         │
    ┌────┴─────┬─────────┬─────────┐
    │          │         │         │
┌───▼───┐  ┌───▼──┐  ┌───▼──┐  ┌──▼──┐
│Cache1 │  │Cache2│  │Cache3│  │...  │ (Individual JSON files)
└───────┘  └──────┘  └──────┘  └─────┘

关键设计模式

• 多源架构每个JSON文件都有自己的缓存实例
• 缓存管理器模式路由和统计的中央协调员
• 嵌套键解析用于深度对象访问的递归点符号解析
• stdio 传输标准MCP协议通信
• 错误隔离失败的源不会导致整个服务器崩溃

演出

基准（或基准测试）

• 查询响应时间典型键查找时间小于10毫秒
• 内存使用情况约1.5倍原始JSON文件大小
• 启动时间10MB总JSON数据的处理时间小于100毫秒
• 并发查询处理100+个并发请求

优化技巧

1. 使用一手资料马克经常访问的资源包括 "primary": true
2. 启用文件监视仅适用于频繁更改的文件
3. 监控内存使用情况使用网页仪表板来追踪消费情况
4. 关键字前缀过滤使用前缀过滤器来减少结果集

发展

项目结构

mcp-json-cache/
├── src/
│   ├── index.ts              # Main MCP server entry point
│   ├── cache/
│   │   ├── JsonCache.ts      # Individual JSON file cache
│   │   └── CacheManager.ts   # Multi-source coordinator
│   ├── mcp/
│   │   └── tools.ts          # MCP tool implementations
│   ├── web/
│   │   ├── server.ts         # Web UI server
│   │   └── routes/           # API routes
│   └── utils/
│       ├── logger.ts         # Structured logging
│       └── config.ts         # Configuration management
├── config/
│   └── default.json          # Default configuration
├── dist/                     # Compiled JavaScript
└── package.json

脚本

# Development
npm run dev              # Run with ts-node
npm run watch            # Watch mode with auto-compile
npm run build            # Compile to dist/
npm start                # Run compiled version

# Web Server Only
npm run web              # Run only the web management UI

# Testing
npm test                 # Run tests
npm run test:watch       # Test in watch mode

# Linting
npm run lint             # ESLint
npm run lint:fix         # Auto-fix linting issues

仅限Web服务器

仅运行网页管理界面，不运行MCP服务器：

# Set your JSON file
set JSON_FILE=test.json

# Run only the web server
npm run web

然后访问以下网址的网页界面：

http://localhost:6315

添加新功能

1. 新的MCP工具添加到 src/mcp/tools.ts
2. Web UI 路由添加到 src/web/routes/
3. 缓存功能扩展 src/cache/ 班级；课程（复数形式，表示多个班级或课程）
4. 配置更新 src/utils/config.ts

故障排除

常见问题

服务器无法启动：

• 检查是否已安装 Node.js 16+
• 验证 npm install 成功完成
• 如果请求的端口被占用，服务器会自动查找可用端口（尝试6315-6325）

JSON 文件无法加载：

• 验证文件路径是否正确且为绝对路径
• 使用在线验证器检查JSON语法
• 确保文件权限允许读取

无法访问Web用户界面：

• 确认 WEB_ENABLED=true （默认）
• 检查指定端口的防火墙设置
• 验证服务器是否成功启动（查看控制台日志）

MCP工具无法正常工作：

• 确保服务器正在运行（npm start）
• 检查Claude代码配置 .claude/settings.local.json
• 验证编译结果 dist/index.js 存在

调试模式

启用调试日志记录：

set LOG_LEVEL=debug
npm start

这将显示以下方面的详细信息：

• 配置加载
• JSON文件解析
• 缓存操作
• Web服务器请求
• MCP工具调用

日志文件

• 控制台日志实时服务器输出（标准错误）
• 网页用户界面日志可通过“日志”选项卡访问 http://localhost:6315
• 错误日志文件加载失败和MCP错误

做出贡献

1. 为仓库创建分支（或：克隆仓库）
2. 创建一个特性分支： git checkout -b feature-name
3. 进行更改并添加测试
4. 运行测试： npm test
5. 构建项目： npm run build
6. 提交一个拉取请求

许可证

\[在此添加您的许可证信息\]

支持

对于问题和疑问：

• 查看上面的故障排除部分
• 查看配置示例
• 启用调试模式以获取详细日志
• 检查网页用户界面仪表板以查看系统状态