🤖 Claude Code Assistant

一个使用LangGraph和**MCP（模型上下文协议）**构建的极简AI编码助手。该项目展示了如何创建具有简洁架构的功能性编码助手，剥离复杂性以理解核心概念。

特性

• 状态图工作流：干净的三节点架构（用户输入 → 模型响应 → 工具使用）
• 持久状态：基于SQLite的对话历史检查点
• 本地工具：文件操作、pytest集成、代码搜索
• MCP集成：桌面指挥官、DuckDuckGo、GitHub（可选）
• 丰富的终端UI：彩色黑客风格界面，带有表情符号
• 调试：在SQLite中跟踪完整的对话历史记录

快速开始

先决条件

• Python 3.11+
• uv（Python包管理器）
• Docker（可选，用于MCP服务器）
• Anthropic API密钥

安装

1. 克隆并导航到项目：

cd claude-code-tool

2. 设置环境变量：

cp .env.example .env
# 编辑.env并添加你的ANTHROPIC_API_KEY

3. 创建虚拟环境并安装依赖项：

# uv会自动创建.venv并安装依赖项
uv sync

4. 运行助手：

uv run main.py

使用方法

启动后，你会看到一个彩色的终端界面。尝试这些命令：

基本命令

help          - 显示帮助信息
tools         - 列出所有可用工具
exit/quit/q   - 退出助手

示例查询

"显示main.py的内容"
"你有哪些工具？"
"列出当前目录下的所有Python文件"
"运行单元测试"
"在代码库中搜索'agent'"
"读取README文件"

可用工具

本地工具（内置）

• read_file：读取文件内容
• list_files：列出目录内容
• write_file：写入文件内容
• run_pytest：执行pytest测试
• search_files：按模式搜索文件
• get_file_info：获取详细文件信息

MCP工具（可选）

要启用MCP工具，你需要安装相应的MCP服务器：

桌面指挥官（文件系统操作）

npm install -g @modelcontextprotocol/server-filesystem

DuckDuckGo（网络搜索）

npm install -g @modelcontextprotocol/server-duckduckgo

GitHub（仓库管理）

npm install -g @modelcontextprotocol/server-github
# 在.env中设置GITHUB_TOKEN

沙箱Python（基于Docker）

# 构建Deno Docker镜像
docker build -t deno-docker:latest -f ./mcps/deno/Dockerfile ./mcps/deno

状态持久化与调试

所有对话都保存在checkpoints.db中。你可以检查状态：

# 查看最近的写入
sqlite3 checkpoints.db "SELECT * FROM writes LIMIT 5"

# 查看检查点
sqlite3 checkpoints.db "SELECT * FROM checkpoints LIMIT 5"

配置

环境变量

创建一个.env文件，包含：

# 必需
ANTHROPIC_API_KEY=your_anthropic_api_key

# 可选
GITHUB_TOKEN=your_github_token

自定义工具

要添加自定义工具，请编辑tools/local_tools.py：

from langchain_core.tools import tool

@tool
def my_custom_tool(param: str) -> str:
    """工具描述"""
    # 你的实现
    return result

# 添加到get_local_tools()
def get_local_tools():
    return [
        # ... 现有工具
        my_custom_tool,
    ]

项目结构

claude-code-tool/
├── main.py                 # 入口点
├── agent.py                # 核心代理实现
├── tools/
│   ├── __init__.py
│   ├── local_tools.py      # 本地工具实现
│   └── mcp_tools.py        # MCP工具集成
├── mcps/
│   └── deno/
│       └── Dockerfile      # Deno MCP容器
├── pyproject.toml          # 依赖项
├── .env.example            # 环境模板
├── .gitignore
└── README.md

UI定制

助手使用Rich进行终端UI。在agent.py中自定义外观：

• Banner：_display_welcome()
• 颜色：修改样式字符串（例如，[bold cyan]）
• 面板：调整Panel()配置

测试

助手包括pytest集成。要测试：

# 向助手询问
"运行单元测试"

# 或手动
uv run pytest -v

安全考虑

• 文件访问：默认情况下，工具可以访问整个文件系统。考虑在生产环境中限制访问。
• 代码执行：沙箱Python MCP在Docker/Deno中运行以实现隔离。
• API密钥：不要提交.env文件。使用环境变量。
• 工具权限：审查工具描述并限制敏感操作。

贡献

欢迎贡献！改进领域：

• 为破坏性操作添加人工审批
• 实现RAG用于个人笔记（Notion、Obsidian）
• 添加更多MCP集成
• 改进错误处理和恢复
• 添加对话导出/导入
• Web UI界面

工作原理

状态图流程

1. 用户输入：收集用户查询
2. 模型响应：Claude处理输入并决定是否使用工具
3. 工具使用（有条件）：如果请求，则执行工具
4. 循环：返回到模型响应，或回到用户输入

检查点

LangGraph的SQLite检查点在每一步之后保存整个对话状态：

• 允许在崩溃后恢复对话
• 便于调试和分析
• 支持多轮次上下文保留

MCP集成

根据需要启动模型上下文协议服务器：

• 当调用工具时，容器启动
• 执行完成后终止进程
• 最小资源开销
• 清晰的责任分离

资源

• LangGraph 文档
• 模型上下文协议
• Anthropic Claude API
• Rich 终端库

---

愉快编码！🚀

有任何问题或意见？欢迎随时提出问题或贡献！

输出格式

直接输出翻译后的中文技术文档，保持完整Markdown格式。