MCP 服务器

Karpathy Guidelines MCP Server

Provides code review and guideline loading based on Andrej Karpathy's coding principles, helping LLMs avoid common pitfalls like over-engineering and unnecessary changes.

README

Karpathy Guidelines MCP Server

</div>

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

简介

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              # 项目说明