Karpathy Guidelines MCP Server

基于 Andrej Karpathy 对 LLM 编码陷阱的观察，将编码行为准则封装为 MCP 工具，供 Claude Code 直接调用。

目录

• 简介
• 功能特性
• 快速开始
• 使用指南
• API 文档
• 四大原则
• 项目结构
• 贡献指南
• 开源协议

简介

LLM 编码时常见的问题：代你做错误假设、过度复杂化代码、改动不该碰的代码、缺乏可验证的成功标准。

本项目将 Andrej Karpathy 提出的四大编码原则封装为 MCP（Model Context Protocol）服务器，提供两个工具：

• get_guidelines — 加载完整的编码行为准则
• review_code — 根据四大原则审查代码并给出改进建议

功能特性

• 🔍 代码审查 — 自动检测过度工程、缺失测试、超出范围的改动等问题
• 📖 指南加载 — 一键获取完整的 Karpathy 编码准则
• 🔌 即插即用 — 标准 MCP 协议，兼容所有支持 MCP 的客户端
• 📦 npx 直接运行 — 无需手动下载，npx 一行命令搞定

快速开始

前置条件

• Node.js >= 18
• Claude Code 或其他 MCP 客户端

安装配置

在 Claude Code 的 MCP 配置文件中添加：

全局配置（~/.claude/settings.json）：

{
  "mcpServers": {
    "karpathy-guidelines": {
      "command": "npx",
      "args": ["-y", "karpathy-guidelines-mcp"]
    }
  }
}

项目级配置（.claude/settings.json）：

{
  "mcpServers": {
    "karpathy-guidelines": {
      "command": "npx",
      "args": ["-y", "karpathy-guidelines-mcp"]
    }
  }
}

配置完成后重启 Claude Code 即可使用。

使用指南

加载编码指南

在编写代码前，让 Claude 加载行为准则：

帮我加载 karpathy 编码指南

审查代码

将代码交给 Claude 审查：

用 karpathy guidelines 审查一下这段代码：

function createUser(data) {
  const validator = new UserValidator();
  const transformer = new DataTransformer();
  const repository = new UserRepository();
  const result = validator.validate(data);
  if (result.isValid) {
    const transformed = transformer.transform(data);
    return repository.save(transformed);
  }
  throw new ValidationError(result.errors);
}

本地开发运行

git clone https://github.com/Yangleduo00337788/Karpathy-Guidelines-MCP-Server.git
cd Karpathy-Guidelines-MCP-Server/mcp-server
npm install
node index.js

API 文档

get_guidelines

返回完整的 Karpathy 编码指南。

| 参数 | 类型 | 必填 | 说明 | |------|------|------|------| | 无 | - | - | - |

返回值： 完整的编码指南文本

review_code

根据四大原则审查代码，返回结构化的审查意见。

| 参数 | 类型 | 必填 | 说明 | |------|------|------|------| | code | string | ✅ | 待审查的代码片段 | | context | string | ❌ | 代码的用途说明（不提供会提示补充） |

返回值： 审查意见列表，包含问题描述和改进建议

检查规则：

| 原则 | 检查内容 | |------|---------| | Think Before Coding | 是否提供了足够的上下文和假设说明 | | Simplicity First | 代码行数是否过多，是否有过度抽象 | | Surgical Changes | 是否有超出请求范围的改动 | | Goal-Driven Execution | 是否有测试来验证代码 |

四大原则

| 原则 | 核心理念 | 解决的问题 | |------|---------|-----------| | 编码前思考 | 不要假设，不要隐藏困惑 | 错误假设、缺少权衡 | | 简洁优先 | 用最少的代码解决问题 | 过度工程、臃肿抽象 | | 精准修改 | 只碰必须碰的 | 无关编辑、改动不该碰的代码 | | 目标驱动执行 | 定义成功标准，循环验证 | 模糊的成功标准、缺乏测试 |

项目结构

Karpathy-Guidelines-MCP-Server/
├── mcp-server/
│   ├── index.js           # MCP 服务器主文件
│   ├── package.json       # 依赖配置
│   └── README.md          # 本文件
├── skills/
│   └── karpathy-guidelines/
│       └── SKILL.md       # 原始技能定义
├── CLAUDE.md              # Claude Code 指南
└── README.md              # 项目说明

贡献指南

欢迎提交 Issue 和 Pull Request。

1. Fork 本仓库
2. 创建特性分支：git checkout -b feature/your-feature
3. 提交更改：git commit -m 'feat: add some feature'
4. 推送分支：git push origin feature/your-feature
5. 提交 Pull Request

Commit 规范

遵循 Conventional Commits 规范：

• feat: 新功能
• fix: Bug 修复
• docs: 文档更新
• refactor: 代码重构
• test: 测试相关
• chore: 构建/工具相关

开源协议

MIT License

如果这个项目对你有帮助，欢迎 ⭐ Star 支持！