MCP 规则管理服务

基于 Model Context Protocol (MCP) 的编码规则管理系统，让 AI 严格遵守你的编码规范。

✨ 功能特性

• 🔐 多用户隔离 - 每个用户拥有独立的私有规则空间，互不干扰
• 📦 规则管理 - 支持上传、加载、卸载、删除规则文件
• 🌐 公共规则 - 管理员可维护全局公共规则，所有用户共享
• 🔄 会话隔离 - 不同客户端/窗口的规则加载状态独立
• 🛡️ 并发安全 - 细粒度锁机制，支持高并发访问
• 📊 内存监控 - 实时监控内存使用，自动清理过期资源
• 📤 大文件支持 - 分片上传机制，支持大型规则文件

🚀 快速开始

环境要求

• Python >= 3.13
• uv 包管理器

安装依赖

uv venv

uv pip install .

启动服务

管理员服务 (端口 8000)：

nohup uv run -m mkrules_mcp.main_admin > admin.log 2>&1 &

用户服务 (端口 8001)：

nohup uv run -m mkrules_mcp.main_user > user.log 2>&1 &

默认管理员账号

项目	值
API_KEY	admin_secure_key_2025

⚠️ 生产环境请务必修改默认密钥！

📖 使用指南

1. 创建用户

管理员调用 create_user 工具创建新用户，系统自动生成用户ID和API密钥。

2. 配置客户端

MCP 客户端配置示例

在支持 MCP 的客户端（如 Trae、Claude Desktop 等）配置文件中添加：

用户服务配置：

{
  "mcpServers": {
    "coding-rules-user": {
      "url": "http://YOUR_SERVER_IP:8001/sse",
      "headers": {
        "Authorization": "Bearer YOUR_API_KEY"
      }
    }
  }
}

管理员服务配置：

{
  "mcpServers": {
    "coding-rules-admin": {
      "url": "http://YOUR_SERVER_IP:8000/sse",
      "headers": {
        "Authorization": "Bearer ADMIN_API_KEY"
      }
    }
  }
}

配置说明

字段	说明
url	服务地址，格式为 http://IP:PORT/sse
Authorization	认证头，格式为 Bearer YOUR_API_KEY

常见客户端配置位置

客户端	配置文件位置
Trae IDE	设置 → MCP 服务器配置
Claude Desktop	~/Library/Application Support/Claude/claude_desktop_config.json
VS Code (MCP插件)	.vscode/mcp.json

3. 基础操作流程

上传规则 → 加载规则 → 下载规则到AI记忆 → 执行编码任务

上传私有规则

upload_private_rule(content="规则内容", filename="java编码规范.md")

加载规则

load_rules(private_filenames="java编码规范.md")

下载规则到AI记忆

download_rules(confirm=True)

执行编码任务

exec_with_rules(task="写一个用户增删改查接口")

🔧 配置说明

核心配置项

配置项	默认值	说明
SESSION_TIMEOUT_SECONDS	18000	会话超时时间（5小时）
SESSION_CLEANUP_INTERVAL_SECONDS	300	清理检查间隔（5分钟）
CHUNK_UPLOAD_TIMEOUT_SECONDS	3600	分片上传超时时间（1小时）

数据存储位置

优先级：

1. 环境变量 MKRULES_DATA_DIR
2. 用户主目录 ~/.mkrules_mcp
3. 当前目录 ./mkrules_data

🛠️ 工具列表

用户端工具

工具名称	功能
list_private_rules	查看私有规则列表
list_public_rules	查看公共规则列表
load_rules	加载规则
unload_rules	卸载规则
download_rules	下载规则到AI记忆
exec_with_rules	基于规则执行任务
upload_private_rule	上传私有规则
delete_private_rule	删除私有规则
get_usage_tutorial	获取使用教程

管理员专属工具

工具名称	功能
create_user	创建新用户
list_users	查看所有用户
disable_user	禁用用户
upload_public_rule	上传公共规则
update_public_rule	更新公共规则
delete_public_rule	删除公共规则
get_system_stats	获取系统监控信息
force_cleanup_sessions	强制清理会话

📊 系统监控

查看系统状态

管理员可调用 get_system_stats 查看实时监控数据：

• 活跃会话数
• 内存使用统计
• 锁对象数量
• 清理回调状态

内存监控指标

指标	说明
user_context_size	用户上下文数量
thread_locks_size	线程锁记录数
chunk_upload_state_size	分片上传任务数

🔒 安全建议

生产环境必做

1. ✅ 修改默认管理员 API_KEY
2. ✅ 启用 HTTPS 加密传输
3. ✅ 启用 DNS 重绑定保护
4. ✅ 配置 API 频率限制
5. ✅ 将日志级别改为 INFO

修改默认密钥

编辑 src/mkrules_mcp/config.py：

INIT_ADMIN_API_KEY = "your_secure_key_here"

或使用环境变量：

export ADMIN_API_KEY="your_secure_key_here"

📁 项目结构

mkRules_MCP/
├── src/mkrules_mcp/
│   ├── main_admin.py      # 管理员服务入口
│   ├── main_user.py       # 用户服务入口
│   ├── user_manager.py    # 用户管理模块
│   ├── session_manager.py # 会话管理模块
│   ├── lock_manager.py    # 锁管理模块
│   ├── config.py          # 配置模块
│   └── fingerprint.py     # 规则指纹模块
├── rules/
│   └── public/            # 公共规则目录
├── pyproject.toml
└── README.md

🔄 资源回收机制

触发条件

• 会话超过 5 小时未活跃
• 分片上传超过 1 小时未完成

回收内容

类型	说明
会话上下文	规则加载状态
用户锁对象	释放内存
分片上传状态	取消未完成任务

不影响内容

• ✅ 私有规则文件（持久化存储）
• ✅ 公共规则文件（持久化存储）
• ✅ 用户账号和 API 密钥

📝 规则文件格式

支持格式：

• .md - Markdown 格式
• .mdc - Markdown with Code 格式

建议结构：

# 规则标题

## 一、命名规范
- 类名使用大驼峰
- 方法名使用小驼峰

## 二、代码规范
- 单个方法不超过 80 行
- 避免嵌套超过 3 层