基于 MCP 协议的极简代码规范引导工具
版本：V2.2.1 | 最后更新：2025-9-29
MCP（Model Context Protocol）是一个极简的 AI 代码规范引导器，专为 AI 工具提供快速、准确的编码规范查询服务。V2.0.0 版本进行了重大架构重构，从原先基于文件路径的复杂分析改为基于技术栈和需求的直接映射机制。
通过智能匹配算法，AI 传入完整上下文描述（如"用 React 写用户登录页组件"），MCP 直接返回精简提示词（如"React 组件用 PascalCase 命名，TypeScript 类型安全"）。
- 毫秒级响应：基于技术栈的直接映射机制，响应速度提升 40%+
- 零配置成本：简单 YAML 配置，部署和维护成本归零
- 智能匹配：支持多技术栈查询，相关规范智能返回，按相关性排序
- 极简设计：纯 MCP 协议服务，专注核心功能
- Docker 支持：完整的容器化部署方案，支持 Docker 和 Docker Compose
- npm 包管理：完成基础的配置，暂时不支持
- 技术栈识别：基于技术栈和需求进行直接映射查询
- 倒排索引搜索：采用倒排索引技术，实现毫秒级智能搜索
- 智能匹配算法：支持多技术栈匹配，相关规范智能返回，按相关性排序
- 中文分词优化：保持技术词汇完整性，提升中文查询准确性
- 精准规范返回：返回最相关的编码规范提示词
- 多场景支持：覆盖前端、后端、数据库等多种开发场景
- 倒排索引技术：构建高效的倒排索引，支持快速全文检索
- 技术关键词权重：React、Vue 等技术关键词权重大幅提升
- 通用词汇过滤：降低"项目"、"用户"等通用名词权重，减少干扰
- 组合规范匹配：支持多技术栈组合场景的规范查询
- 相关性评分：基于多因子算法计算匹配相关性分数
- 结果数量保证：确保返回完整的 3 条匹配规范
- 服务状态监控：实时检查 MCP 服务运行状态
- 配置验证：验证 YAML 配置文件格式正确性
- 快速诊断：提供服务可用性检查
传统 AI 工具需要每次请求都附加冗长的团队规范描述，导致模型响应速度下降 40%。MCP 通过动态注入极短提示词的方式，让 AI 工具快速理解团队架构规范，无需重复描述。
- Python: 3.9 或更高版本（推荐 3.11+）
- Node.js: 18.20.8 或更高版本（用于包管理）
- 操作系统: Windows 10/11, macOS, Linux
- 内存: 最低 512MB，推荐 1GB+（用于缓存优化）
- 代码编辑器: VS Code, Cursor 等支持 AI 辅助的编辑器
- 包管理器: pip (Python), npm (Node.js)
- 版本控制: Git
- JSON工具: jq（用于API测试）
# 环境变量配置（可选）
export MCP_CACHE_SIZE=1000 # 分词缓存大小（默认1000）
export MCP_CACHE_TTL=3600*24 # 缓存生存时间（秒，默认24小时）
export MCP_LOG_LEVEL=INFO # 日志级别（DEBUG/INFO/WARNING/ERROR）
export MCP_MAX_RESULTS=3 # 最大返回结果数（默认3）| 部署方式 | CPU | 内存 | 磁盘 | 网络 |
|---|---|---|---|---|
| 本地开发 | 1核+ | 512MB+ | 100MB | - |
| Docker单容器 | 1核+ | 1GB+ | 200MB | - |
| 生产环境 | 2核+ | 2GB+ | 500MB | 1Mbps+ |
- 查询响应时间: < 5ms（倒排索引）
- 缓存命中率: 50-70%（正常使用）
- 并发支持: 100+ 请求/秒
- 内存使用: 50-200MB（运行时）
本项目支持三种部署方式，您可以根据需求选择最适合的方案：
注意：此方式需要项目发布到 npm registry，目前项目尚未发布。
# 直接运行 MCP 服务器（无需克隆项目）
npx linter-mcp
# 查看帮助信息
npx linter-mcp --help优势：
- 🚀 零配置启动：无需手动克隆项目或安装依赖
- ⚡ 即用即走：npx 自动下载并运行最新版本
- 🔄 自动更新：每次运行都使用最新版本
- 🛡️ 环境隔离：不会污染本地环境
# 克隆项目
git clone https://github.com/Daniele111222/linter-mcp.git
cd linter-mcp
# 构建并启动服务
docker-compose up -d
# 查看服务状态
docker-compose ps
# 查看日志
docker-compose logs -f linter-mcp
# 停止服务
docker-compose down# 构建镜像
docker build -t linter-mcp .
# 运行容器
docker run -it --rm \
-v $(pwd)/config.yaml:/app/config.yaml:ro \
linter-mcp
# 后台运行
docker run -d --name linter-mcp-server \
-v $(pwd)/config.yaml:/app/config.yaml:ro \
--restart unless-stopped \
linter-mcp优势：
- 🐳 环境一致性：确保在任何环境中都能稳定运行
- 📦 依赖隔离：不影响宿主机环境
- 🔧 易于部署：一键构建和启动
- 🔄 便于扩展：支持容器编排和集群部署
git clone https://github.com/Daniele111222/linter-mcp.git
cd linter-mcp# 创建虚拟环境（推荐）
python -m venv venv
# 激活虚拟环境
# Windows
venv\Scripts\activate
# macOS/Linux
source venv/bin/activate
# 安装依赖
pip install -r requirements.txt优势：
- 🛠️ 开发友好：便于调试和修改代码
- 🎯 精确控制：可以精确控制 Python 版本和依赖
- 📝 易于定制：方便添加自定义功能
根据您选择的部署方式，使用对应的启动方法：
# 直接启动 MCP 服务器
npx linter-mcp
# 查看帮助信息
npx linter-mcp --help# 启动服务（后台运行）
docker-compose up -d
# 启动开发模式（前台运行，便于调试）
docker-compose --profile dev up linter-mcp-dev
# 查看实时日志
docker-compose logs -f linter-mcp# 交互式运行（前台）
docker run -it --rm linter-mcp
# 后台运行
docker run -d --name linter-mcp-server linter-mcp# 确保虚拟环境已激活
# Windows: venv\Scripts\activate
# macOS/Linux: source venv/bin/activate
# 启动 MCP 服务器（标准输入输出模式）
python mcp_stdio_server.py
# 或启动 HTTP API 模式
python -m src.main根据您的部署方式，使用对应的验证方法：
# 检查服务状态
curl http://localhost:8080/ping
# 测试规范获取
curl -X POST http://localhost:8080/get_standards \
-H "Content-Type: application/json" \
-d '{"context": "react"}'# 检查容器状态
docker-compose ps
# 查看容器日志
docker-compose logs linter-mcp
# 进入容器进行调试
docker-compose exec linter-mcp bash
# 检查容器健康状态
docker inspect --format='{{.State.Health.Status}}' linter-mcp-server# 测试 MCP 标准输入输出通信
echo '{"jsonrpc": "2.0", "method": "ping", "id": 1}' | python mcp_stdio_server.py
# 或使用 npx
echo '{"jsonrpc": "2.0", "method": "ping", "id": 1}' | npx linter-mcp# 使用 npx 直接启动 MCP 服务器
npx linter-mcp# 使用 Docker Compose 启动
docker-compose up -d
# 查看服务状态
docker-compose ps# 激活虚拟环境后启动
python mcp_stdio_server.py{
"mcpServers": {
"linter-mcp": {
"command": "npx",
"args": ["linter-mcp"],
"env": {}
}
}
}{
"mcpServers": {
"linter-mcp": {
"command": "docker",
"args": ["run", "-i", "--rm", "linter-mcp"],
"env": {}
}
}
}请求示例：
curl -X POST http://localhost:8080/get_standards \
-H "Content-Type: application/json" \
-d '{"context": "React组件开发"}'请求参数：
{
"context": "string" // 必填，代码上下文描述
}响应示例：
{
"success": true,
"data": {
"standards": [
"使用函数式组件和React Hooks",
"组件名称使用PascalCase命名",
"使用TypeScript进行类型定义"
],
"matched_keywords": ["React", "组件"],
"query_time_ms": 2.5,
"cache_hit": true
},
"message": "获取编码规范成功"
}请求示例：
curl http://localhost:8080/ping响应示例：
{
"success": true,
"data": {
"status": "healthy",
"uptime_seconds": 3600,
"version": "2.2.1",
"config_loaded": true
},
"message": "服务运行正常"
}请求示例：
curl http://localhost:8080/config/info响应示例：
{
"success": true,
"data": {
"version": "2.2.1",
"name": "MCP极简代码规范引导器",
"standards_count": 25,
"components_enabled": false,
"cache_enabled": true
},
"message": "配置信息获取成功"
}请求示例：
curl -X POST http://localhost:8080/config/reload响应示例：
{
"success": true,
"data": {
"reloaded": true,
"standards_count": 25,
"reload_time": "2024-01-15T10:30:00Z"
},
"message": "配置重载成功"
}请求示例：
curl http://localhost:8080/cache/stats响应示例：
{
"success": true,
"data": {
"tokenize_cache": {
"hits": 579,
"misses": 421,
"hit_rate": 0.579,
"evictions": 15,
"current_size": 856,
"max_size": 1000,
"performance_level": "Medium"
},
"engine_performance": {
"total_queries": 1000,
"index_queries": 800,
"fallback_queries": 200,
"avg_query_time_ms": 2.5
}
},
"message": "缓存统计获取成功"
}请求示例：
curl -X POST http://localhost:8080/cache/clear响应示例：
{
"success": true,
"data": {
"cleared": true,
"previous_size": 856,
"clear_time": "2024-01-15T10:35:00Z"
},
"message": "缓存清空成功"
}{
"success": false,
"data": null,
"message": "错误描述信息",
"error_code": "ERROR_CODE"
}常见错误码：
INVALID_REQUEST: 请求参数无效CONFIG_NOT_LOADED: 配置文件未加载INTERNAL_ERROR: 内部服务错误
编辑 config.yaml 文件添加自定义规范映射：
standards_mapping:
"your_tech_stack": "你的编码规范描述..."通过挂载自定义配置文件：
# 挂载自定义配置
docker run -it --rm \
-v /path/to/your/config.yaml:/app/config.yaml:ro \
linter-mcp或修改 docker-compose.yml 中的卷挂载：
volumes:
- ./your-custom-config.yaml:/app/config.yaml:rolinter-mcp/
├── src/ # 核心源代码目录
│ ├── __init__.py # 包初始化文件
│ ├── main.py # FastAPI主服务模块，HTTP API入口
│ ├── engine.py # MCP规则匹配引擎（V2.1.0集成倒排索引）
│ ├── inverted_index.py # 倒排索引模块（V2.2.1新增分词缓存优化）
│ ├── mcp_handler.py # MCP协议处理器，处理JSON-RPC通信
│ ├── models.py # Pydantic数据模型定义
│ ├── config.py # 配置管理器，YAML配置加载
│ ├── component_engine.py # 组件信息引擎（开发中）
│ ├── logger.py # 日志配置模块
│ ├── version.py # 版本信息管理
│ └── config.yaml # 源代码目录配置文件
├── bin/ # 可执行文件目录
│ └── linter-mcp # NPX启动脚本（Node.js包装器）
├── MCP服务配置样例/ # MCP客户端配置示例目录
│ ├── mcp_config_docker.json # Docker方式MCP配置示例
│ └── mcp_config_example.json # 标准MCP配置示例
├── .vercel/ # Vercel部署配置目录
│ └── project.json # Vercel项目配置
├── config.yaml # 主配置文件（编码规范映射）
├── mcp_stdio_server.py # MCP标准输入输出服务器入口
├── requirements.txt # Python依赖包列表
├── package.json # NPM包配置文件
├── package-lock.json # NPM依赖锁定文件
├── Dockerfile # Docker镜像构建文件
├── docker-compose.yml # Docker Compose编排配置
├── .gitignore # Git忽略文件配置
├── .dockerignore # Docker构建忽略文件
├── comprehensive_frontend_test.py # 前端功能综合测试脚本
├── test_cache_optimization.py # 缓存优化测试脚本
├── test_cache_optimization_new.py # 新版缓存优化测试脚本
├── test_mcp_real_scenarios.py # MCP真实场景测试脚本
└── README.md # 项目文档
包含所有Python源代码模块，采用模块化设计，职责分离清晰。
包含NPX启动脚本，支持通过npm生态系统快速启动服务。
提供不同部署方式的MCP客户端配置示例，便于用户快速集成。
comprehensive_frontend_test.py: 前端功能综合测试test_cache_optimization*.py: 缓存优化相关测试test_mcp_real_scenarios.py: MCP协议真实场景测试
- config.yaml: 主配置文件，定义编码规范映射关系
- package.json: NPM包配置，支持npx快速启动
- requirements.txt: Python依赖包管理
- docker-compose.yml: 容器编排配置，支持开发和生产环境
- mcp_stdio_server.py: MCP协议标准输入输出服务器主入口
- src/main.py: FastAPI HTTP服务器入口，提供REST API接口
- Dockerfile: 容器化部署配置，支持多阶段构建
- .vercel/: Vercel云平台部署配置
- bin/linter-mcp: Node.js包装脚本，实现跨平台启动
- FastAPI应用主入口，定义所有HTTP API路由
- 生命周期管理，包括启动和关闭事件处理
- 全局中间件配置，请求ID生成和日志记录
- 健康检查和服务状态监控接口
- V2.1.0集成倒排索引优化，实现毫秒级查询响应
- 智能匹配算法，支持多技术栈组合查询
- 性能统计和监控，包括查询时间和命中率统计
- 向后兼容的传统匹配模式，确保系统稳定性
- V2.2.1新增分词缓存优化，性能提升94.8%
- LRU + TTL双重缓存策略，智能内存管理
- 线程安全设计，支持多线程并发访问
- 中文分词优化，保持技术词汇完整性
- 预编译正则表达式，减少重复编译开销
- JSON-RPC 2.0协议实现，处理MCP客户端通信
- 工具注册和调用管理，支持动态工具发现
- 错误处理和异常管理，确保协议通信稳定性
- 标准输入输出流处理，支持MCP标准通信模式
- Pydantic数据模型，定义API请求和响应格式
- JSON-RPC协议模型，包括请求、响应和错误处理
- MCP服务器能力声明和实现信息模型
- 组件信息相关数据模型（开发中功能）
- YAML配置文件加载和解析，支持热重载
- 配置验证和错误处理，确保配置格式正确性
- 全局配置管理器实例，提供统一配置访问接口
- 默认规范和映射规则管理
- 组件库信息查询和管理（开发中功能）
- 支持多框架组件信息（React、Vue、Angular等）
- 组件搜索和过滤功能，基于关键词和标签
- 组件API文档和使用示例管理
- 统一日志配置和管理，支持多级别日志输出
- 文件和控制台双重日志输出，便于调试和监控
- 日志格式化和轮转配置，防止日志文件过大
- 性能监控和错误追踪日志记录
- 项目版本号定义和管理
- 版本兼容性检查和升级提示
- 构建信息和发布时间记录
V2.2.1版本的配置结构包含完整的编码规范映射、组件库配置和缓存优化设置：
# 基本信息
version: "2.2.1"
name: "MCP极简代码规范引导器"
description: "基于MCP协议的极简代码规范引导工具"
# 核心配置：技术栈到规范的直接映射
standards_mapping:
# ===== 命名规范 =====
"目录命名": "目录全部采用小写方式，以中划线分隔，有复数结构时采用复数命名法"
"文件命名": "文件全部采用小写方式，名称为多个单词时以中划线分割"
"组件命名": "组件使用大驼峰命名，例如：SearchHead、Title"
"变量命名": "变量使用小驼峰命名，布尔类型需要标识前缀如has、is、can"
"函数命名": "函数使用小驼峰命名，使用动词或动词+名词形式"
"常量命名": "常量全部大写，使用下划线组合命名"
# ===== 技术栈规范 =====
"react": "React组件用PascalCase命名，使用函数式组件和Hooks"
"vue": "Vue组件用PascalCase命名，使用Composition API"
"javascript": "使用camelCase命名变量和函数，const优于let"
"typescript": "使用TypeScript类型安全，定义接口和类型"
"css": "类名使用小写字母，以中划线分割"
"html": "使用语义化HTML标签，保持良好的可访问性"
# ===== 组合场景 =====
"react+typescript": "React组件用PascalCase命名，使用TypeScript类型安全"
"vue+typescript": "Vue组件用PascalCase命名，使用TypeScript和Composition API"
# 默认规范
"default": "代码风格一致，注释清晰，遵循项目规范"
# 默认通用规范集合
default_standards:
- "文件命名：文件全部采用小写方式，名称为多个单词时以中划线分割"
- "组件命名：组件使用大驼峰命名"
- "变量命名：变量使用小驼峰命名"
- "函数命名：函数使用小驼峰命名，使用动词或动词+名词形式"
- "常量命名：常量全部大写，使用下划线组合命名"
- "CSS类名：类名使用小写字母，以中划线分割"
- "注释规范：要有良好的注释习惯，便于理解、回顾代码"
# ===== 组件信息库配置（开发中） =====
components_library:
name: "通用组件库"
version: "1.0.0"
description: "提供常用前端组件的信息查询和使用指导"
# 组件分类定义
categories:
- name: "基础组件"
description: "基础UI组件，如按钮、输入框等"
keywords: ["button", "input", "基础", "ui"]
- name: "表单组件"
description: "表单相关组件"
keywords: ["form", "表单", "验证", "输入"]
- name: "数据展示"
description: "数据展示相关组件"
keywords: ["table", "list", "card", "数据", "展示"]
# 支持的框架
frameworks:
- name: "react"
display_name: "React"
description: "React框架组件"
- name: "vue"
display_name: "Vue"
description: "Vue框架组件"V2.2.1版本新增的分词缓存优化支持以下配置参数：
# 在初始化InvertedIndex时可配置缓存参数
inverted_index = InvertedIndex(
standards_mapping,
cache_size=1000, # 缓存大小，默认1000条
cache_ttl=3600*24 # 缓存TTL（秒），默认24小时
)- cache_size: LRU缓存最大容量，超出时自动淘汰最久未使用的条目
- cache_ttl: 缓存条目生存时间（秒），过期后自动清理
- 线程安全: 内置线程锁，支持多线程并发访问
- MD5哈希: 使用MD5生成缓存键，确保键的唯一性和安全性
# 获取缓存统计信息
cache_stats = inverted_index.get_cache_statistics()
# 返回：命中率、未命中率、缓存大小、淘汰次数等
# 清空缓存
inverted_index.clear_cache()
# 获取综合统计（包含索引和缓存信息）
comprehensive_stats = inverted_index.get_comprehensive_statistics()- 毫秒级查询：基于倒排索引的快速全文检索
- 中文分词优化：保持技术词汇完整性，提升中文查询准确性
- 技术关键词权重：React、Vue等技术关键词权重大幅提升
- 通用词汇过滤：降低"项目"、"用户"等通用名词权重
- LRU + TTL策略：双重缓存机制，智能内存管理
- 94.8%性能提升：缓存命中时分词耗时降至0.04ms
- 预编译正则：减少重复编译开销，提升处理效率
- 自动过期清理：防止内存泄漏，保持系统稳定
- 配置文件修改后自动重新加载，无需重启服务
- 配置验证和错误处理，确保配置格式正确性
- 向后兼容性保证，支持旧版本配置格式
启动服务时会自动验证配置文件格式。也可以通过健康检查接口验证：
# 检查服务状态和配置
curl http://localhost:8080/ping
# 获取配置信息
curl http://localhost:8080/config# 指定自定义配置文件路径
export MCP_CONFIG_PATH=/path/to/custom/config.yaml
# 启用/禁用倒排索引
export MCP_ENABLE_INDEX=true
# 设置缓存参数
export MCP_CACHE_SIZE=2000
export MCP_CACHE_TTL=7200MCP极简代码规范引导器采用模块化设计，核心架构包含以下几个层次：
┌─────────────────────────────────────────────────────────────┐
│ MCP客户端接口层 │
│ ┌─────────────────┐ ┌─────────────────┐ ┌─────────────────┐ │
│ │ JSON-RPC │ │ HTTP REST │ │ 标准输入输出 │ │
│ │ 接口 │ │ API │ │ 接口 │ │
│ └─────────────────┘ └─────────────────┘ └─────────────────┘ │
└─────────────────────────────────────────────────────────────┘
│
┌─────────────────────────────────────────────────────────────┐
│ 协议处理层 │
│ ┌─────────────────┐ ┌─────────────────┐ ┌─────────────────┐ │
│ │ MCP Handler │ │ FastAPI Main │ │ Logger │ │
│ │ 协议处理器 │ │ HTTP服务 │ │ 日志管理 │ │
│ └─────────────────┘ └─────────────────┘ └─────────────────┘ │
└─────────────────────────────────────────────────────────────┘
│
┌─────────────────────────────────────────────────────────────┐
│ 业务逻辑层 │
│ ┌─────────────────┐ ┌─────────────────┐ ┌─────────────────┐ │
│ │ Rule Engine │ │ Component Engine│ │ Config Manager │ │
│ │ 规则匹配引擎 │ │ 组件信息引擎 │ │ 配置管理器 │ │
│ └─────────────────┘ └─────────────────┘ └─────────────────┘ │
└─────────────────────────────────────────────────────────────┘
│
┌─────────────────────────────────────────────────────────────┐
│ 数据处理层 │
│ ┌─────────────────┐ ┌─────────────────┐ ┌─────────────────┐ │
│ │ Inverted Index │ │ Tokenize Cache │ │ Data Models │ │
│ │ 倒排索引 │ │ 分词缓存 │ │ 数据模型 │ │
│ └─────────────────┘ └─────────────────┘ └─────────────────┘ │
└─────────────────────────────────────────────────────────────┘
技术原理：
- 倒排索引构建：将编码规范文本进行分词，构建词汇到文档的映射关系
- 中文分词优化：采用智能分词算法，保持技术词汇（如"React"、"TypeScript"）的完整性
- 权重计算：技术关键词权重提升，通用词汇权重降低，提升匹配精度
性能优化：
# 倒排索引核心算法
class InvertedIndex:
def __init__(self, standards_mapping):
self.index = {} # 词汇 -> [(关键词, 规范, 权重)]
self.build_index(standards_mapping)
def search(self, query, max_results=3):
# 1. 查询分词
tokens = self.tokenize(query)
# 2. 索引查找
candidates = self.find_candidates(tokens)
# 3. 相关性评分
scored_results = self.calculate_relevance(candidates, tokens)
# 4. 结果排序和返回
return sorted(scored_results, key=lambda x: x[2], reverse=True)[:max_results]技术特性：
- 毫秒级响应：查询响应时间 < 5ms
- 智能匹配：支持模糊匹配和相关性排序
- 多语言支持：中英文混合查询优化
缓存架构：
class TokenizeCache:
def __init__(self, max_size=1000, ttl=3600):
self.cache = {} # 主缓存存储
self.access_order = [] # LRU访问顺序
self.max_size = max_size # 最大缓存容量
self.ttl = ttl # 生存时间（秒）
self.lock = threading.Lock() # 线程安全锁
def get(self, key):
# 1. 检查缓存命中
# 2. 验证TTL有效性
# 3. 更新LRU顺序
# 4. 返回缓存结果
def put(self, key, value):
# 1. 生成MD5哈希键
# 2. 检查容量限制
# 3. LRU淘汰策略
# 4. 存储新条目性能提升数据：
- 缓存命中率：57.9%（实测数据）
- 性能提升：94.8%（缓存命中时）
- 响应时间：0.04ms（缓存命中）vs 0.8ms（缓存未命中）
- 内存效率：LRU策略确保内存使用稳定
线程安全设计：
- 读写锁机制：支持多线程并发访问
- 原子操作：缓存更新操作原子性保证
- 死锁预防：锁获取超时机制
多因子评分系统：
def calculate_relevance_score(query_tokens, candidate_tokens, keyword):
score = 0
# 1. 精确匹配权重（最高）
exact_matches = len(set(query_tokens) & set(candidate_tokens))
score += exact_matches * 10
# 2. 技术关键词权重
tech_keywords = ['react', 'vue', 'typescript', 'javascript']
for token in query_tokens:
if token.lower() in tech_keywords:
score += 5
# 3. 词汇覆盖率
coverage = len(set(query_tokens) & set(candidate_tokens)) / len(query_tokens)
score += coverage * 3
# 4. 长度惩罚（避免过长匹配）
length_penalty = min(len(candidate_tokens) / 10, 1)
score *= (1 - length_penalty * 0.1)
return score匹配策略：
- 精确匹配优先：完全匹配的规范优先返回
- 相关性排序：按评分高低排序结果
- 多结果返回：返回最相关的3条规范
- 组合场景支持：支持多技术栈组合查询
# 引擎性能统计
performance_stats = {
'total_queries': 1000, # 总查询次数
'index_queries': 800, # 索引查询次数
'fallback_queries': 200, # 降级查询次数
'avg_query_time_ms': 2.5 # 平均查询时间
}
# 缓存性能统计
cache_stats = {
'hits': 579, # 缓存命中次数
'misses': 421, # 缓存未命中次数
'hit_rate': 0.579, # 命中率
'evictions': 15, # 淘汰次数
'current_size': 856 # 当前缓存大小
}- High：命中率 > 70%，平均响应时间 < 2ms
- Medium：命中率 50-70%，平均响应时间 2-5ms
- Low：命中率 < 50%，平均响应时间 > 5ms
- 松耦合设计：各模块独立，便于单独升级和维护
- 接口标准化：统一的API接口，支持功能扩展
- 插件机制：支持自定义规则引擎和缓存策略
- 无状态设计：服务实例无状态，支持负载均衡
- 配置外部化：配置文件独立，支持动态更新
- 缓存分布式：支持Redis等分布式缓存（规划中）
# 启动MCP服务器
python -m src.main
# 查看服务状态
curl http://localhost:8080/ping
# 测试规范获取
curl -X POST http://localhost:8080/get_standards \
-H "Content-Type: application/json" \
-d '{"context": "React组件开发"}'- 编辑
config.yaml文件来自定义规范映射 - 参考
mcp_config_example.json进行 MCP 客户端配置 - 查看
logs/目录获取运行日志
# 1. 测试健康检查
curl http://localhost:8080/ping
# 2. 测试规范获取接口
curl -X POST http://localhost:8080/get_standards \
-H "Content-Type: application/json" \
-d '{"context": "React组件开发"}'
# 3. 测试配置信息获取
curl http://localhost:8080/config/info# 4. 查看缓存统计（V2.2.1新增）
curl http://localhost:8080/cache/stats
# 5. 清空缓存（测试环境）
curl -X POST http://localhost:8080/cache/clear
# 6. 重载配置
curl -X POST http://localhost:8080/config/reload#!/bin/bash
# 创建测试脚本 test_api.sh
echo "=== MCP API 功能测试 ==="
# 健康检查
echo "1. 健康检查测试..."
curl -s http://localhost:8080/ping | jq .
# 规范获取测试
echo -e "\n2. 规范获取测试..."
curl -s -X POST http://localhost:8080/get_standards \
-H "Content-Type: application/json" \
-d '{"context": "React TypeScript"}' | jq .
# 缓存统计测试
echo -e "\n3. 缓存统计测试..."
curl -s http://localhost:8080/cache/stats | jq .
echo -e "\n=== 测试完成 ==="运行测试：
chmod +x test_api.sh
./test_api.sh注意:
- 确保服务已启动在
http://localhost:8080 - 需要安装
jq工具来格式化JSON输出 - 当前项目的单元测试模块正在完善中
- Fork 项目 到你的 GitHub 账户
- 创建功能分支:
git checkout -b feature/your-feature-name - 提交更改:
git commit -am 'Add some feature' - 推送分支:
git push origin feature/your-feature-name - 创建 Pull Request
- 遵循 PEP 8 代码风格
- 使用 类型注解 (Type Hints)
- 函数和类需要添加 文档字符串
- 变量命名使用 snake_case
- 类名使用 PascalCase
- 遵循项目中的 前端开发规范.txt
- 组件命名使用 PascalCase
- 文件命名使用 kebab-case
- 变量和函数使用 camelCase
使用语义化提交信息：
feat: 添加新功能
fix: 修复bug
docs: 更新文档
style: 代码格式调整
refactor: 代码重构
test: 添加测试
chore: 构建过程或辅助工具的变动
- 确保所有测试通过
- 更新相关文档
- 在 PR 描述中说明更改内容
- 等待代码审查
- 根据反馈进行修改
Q: 启动时提示端口被占用
# 解决方案：检查端口占用
netstat -ano | findstr :8080
# 或更换端口启动
python -m src.main --port 8081Q: 配置文件加载失败
# 检查config.yaml文件格式
python -c "import yaml; yaml.safe_load(open('config.yaml'))"Q: get_standards 接口返回空结果
- 检查上下文描述是否准确
- 确认 config.yaml 中是否配置了对应的标准映射
- 查看 logs/ 目录中的日志文件获取详细错误信息
Q: MCP 协议连接问题
- 确保使用正确的 MCP 客户端配置
- 参考 mcp_config_example.json 进行配置
- 检查标准输入输出模式是否正常工作
Q: 如何添加新的技术栈规范
# 在config.yaml的standards_mapping中添加新规则
standards_mapping:
"新技术栈": "新技术栈的编码规范描述..."
"组合场景": "多技术栈组合的规范描述..."Q: 如何修改默认规范
# 修改config.yaml中的default_standards
default_standards: "你的默认编码规范描述..."Q: 响应速度慢
- 检查配置文件大小，过大的配置可能影响加载速度
- 考虑使用缓存机制（项目已实现配置缓存）
- 生产环境建议使用多进程部署
本项目采用 ISC 许可证。
ISC License
Copyright (c) 2024, zhuweijie1@hyperchain.cn
Permission to use, copy, modify, and/or distribute this software for any
purpose with or without fee is hereby granted, provided that the above
copyright notice and this permission notice appear in all copies.
THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
WHATSOever RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
主要依赖项及其许可证：
- FastAPI: MIT License
- Uvicorn: BSD License
- PyYAML: MIT License
- Pydantic: MIT License
- 作者: zhuweijie1@hyperchain.cn
- 项目仓库: [https://github.com/Daniele111222/linter-mcp.git]
- 问题反馈: [https://github.com/Daniele111222/linter-mcp/issues]
- 🚀 分词缓存优化：全新 TokenizeCache 类，实现智能分词缓存机制
- 集成 LRU + TTL 双重缓存策略，自动管理缓存生命周期
- 线程安全设计，支持多线程并发访问
- MD5 哈希键生成，确保缓存键的唯一性和安全性
- ⚡ 性能提升：分词处理性能提升 94.8%
- 缓存命中时分词耗时降至 0.04ms
- 预编译正则表达式，减少重复编译开销
- 智能缓存淘汰机制，防止内存无限增长
- 📊 缓存监控功能：完整的缓存统计和管理体系
- 实时缓存命中率、未命中率统计
- 缓存大小、淘汰次数等详细指标
- 新增
get_cache_statistics()和clear_cache()管理方法
- 🔧 API 增强：新增综合统计功能
get_comprehensive_statistics()提供索引和缓存的全面统计- 性能效率评级（High/Medium/Low）
- 内存使用量估算和优化建议
- 🛡️ 向后兼容：保持原有 API 接口不变，无缝升级体验
- 🐳 Docker 容器化支持：新增完整的 Docker 部署方案
- 添加 Dockerfile 和 docker-compose.yml 配置
- 支持开发和生产环境的容器化部署
- 提供健康检查和自动重启机制
- 📦 npm 包管理支持：集成 npm 生态系统
- 添加 package.json 和 package-lock.json
- 支持 npx 快速启动（准备中）
- 提供 Node.js 包装脚本
- 🔧 部署方式多样化：支持三种部署方式
- NPX 快速部署（零配置）
- Docker 容器化部署（环境一致性）
- 本地 Python 环境部署（开发友好）
- 📚 文档完善：更新部署和使用文档
- 详细的 Docker 部署指南
- npm 包使用说明
- 多种验证方式说明
- 🚀 倒排索引智能搜索：全新倒排索引引擎，实现毫秒级智能搜索
- 🔤 中文分词优化：改进中文分词策略，保持技术词汇完整性
- ⚡ 技术关键词权重提升：React、Vue、Component 等技术关键词权重大幅提升
- 🎯 通用词汇干扰减少：降低"项目"、"用户"等通用名词权重，提升匹配精度
- 📊 返回结果数量修复：支持返回 3 条强相关的规范
- 🔍 匹配准确性大幅提升：优化评分算法，技术栈匹配准确率提升 60%+
- ⚡ 响应速度进一步优化：倒排索引技术使查询响应速度再次提升
- ✨ 智能匹配算法升级：支持多技术栈查询时返回所有相关规范
- 🔍 相关规范智能返回：查询特定技术栈时自动返回相关规范（如模块化、响应式等）
- 📊 结果排序优化：按相关性对返回结果进行智能排序
- 🎯 匹配准确性提升：改进匹配算法，提供更精准的规范建议
- 🧹 项目结构优化：清理测试文件，更新.gitignore，优化项目结构
- 🚀 重大架构重构：从基于文件路径改为基于技术栈和需求的直接映射
- ⚡ 性能大幅提升：响应速度提升 40%+，毫秒级响应
- 📋 配置极简化：移除复杂的 file_patterns 配置，采用简单的 standards_mapping
- 🔧 查询方式革新：AI 直接传入技术栈上下文，无需文件路径分析
- 🎯 精准匹配：基于技术栈关键词的直接映射机制
- 🐛 Bug 修复：修复基于文件路径的配置读取问题
- 📚 文档完善：补充文件路径匹配的使用说明
- 🔧 稳定性提升：优化文件路径解析的错误处理
- 🎉 首次发布：基于文件路径的 MCP 服务实现
- 📁 文件路径匹配：支持基于文件路径的代码规范查询
- 🔍 健康检查：服务状态监控功能
- 📋 规范管理：基础的代码规范配置和查询
*最后更新时间: 2025 年 9 月 29 日