# Karpathy Guidelines MCP Server **Repository Path**: yangleduo7788/karpathy-guidelines-mcp-server ## Basic Information - **Project Name**: Karpathy Guidelines MCP Server - **Description**: LLM 编码时常见的问题:代你做错误假设、过度复杂化代码、改动不该碰的代码、缺乏可验证的成功标准。 本项目将 Andrej Karpathy 提出的四大编码原则封装为 MCP(Model Context Protocol)服务器,提供两个工具: get_guidelines — 加载完整的编码行为准则 review_code— 根据四大原则审查代码并给出改进建议 - **Primary Language**: Unknown - **License**: Not specified - **Default Branch**: master - **Homepage**: None - **GVP Project**: No ## Statistics - **Stars**: 1 - **Forks**: 0 - **Created**: 2026-06-04 - **Last Updated**: 2026-06-04 ## Categories & Tags **Categories**: Uncategorized **Tags**: None ## README
[](https://www.npmjs.com/package/karpathy-guidelines-mcp) [](https://opensource.org/licenses/MIT)
> 基于 [Andrej Karpathy](https://x.com/karpathy/status/2015883857489522876) 对 LLM 编码陷阱的观察,将编码行为准则封装为 MCP 工具,供 Claude Code 直接调用。 ## 目录 - [简介](#简介) - [功能特性](#功能特性) - [快速开始](#快速开始) - [使用指南](#使用指南) - [API 文档](#api-文档) - [四大原则](#四大原则) - [项目结构](#项目结构) - [贡献指南](#贡献指南) - [开源协议](#开源协议) ## 简介 LLM 编码时常见的问题:代你做错误假设、过度复杂化代码、改动不该碰的代码、缺乏可验证的成功标准。 本项目将 Andrej Karpathy 提出的四大编码原则封装为 MCP(Model Context Protocol)服务器,提供两个工具: - **`get_guidelines`** — 加载完整的编码行为准则 - **`review_code`** — 根据四大原则审查代码并给出改进建议 ## 功能特性 - 🔍 **代码审查** — 自动检测过度工程、缺失测试、超出范围的改动等问题 - 📖 **指南加载** — 一键获取完整的 Karpathy 编码准则 - 🔌 **即插即用** — 标准 MCP 协议,兼容所有支持 MCP 的客户端 - 📦 **npx 直接运行** — 无需手动下载,`npx` 一行命令搞定 ## 快速开始 ### 前置条件 - [Node.js](https://nodejs.org/) >= 18 - [Claude Code](https://claude.ai/code) 或其他 MCP 客户端 ### 安装配置 在 Claude Code 的 MCP 配置文件中添加: **全局配置**(`~/.claude/settings.json`): ```json { "mcpServers": { "karpathy-guidelines": { "command": "npx", "args": ["-y", "karpathy-guidelines-mcp"] } } } ``` **项目级配置**(`.claude/settings.json`): ```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); } ``` ### 本地开发运行 ```bash 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](https://www.conventionalcommits.org/) 规范: - `feat:` 新功能 - `fix:` Bug 修复 - `docs:` 文档更新 - `refactor:` 代码重构 - `test:` 测试相关 - `chore:` 构建/工具相关 ## 开源协议 [MIT License](./LICENSE) --- > 如果这个项目对你有帮助,欢迎 ⭐ Star 支持!