🤖 Claude代码助理
一个极简主义的人工智能编码助手 LangGraph 和 MCP（模型上下文协议）该项目演示了如何创建一个具有干净架构的功能性编码助手，剥离复杂性以理解核心概念。
特性
- 状态图工作流：干净的三节点架构（user_input→ 模型响应→ 工具使用）
- 持久状态：基于SQLite的对话历史检查点
- 本地工具：文件操作、pytest集成、代码搜索
- MCP集成：桌面指挥官、DuckDuckGo、GitHub（可选）
- 丰富的终端用户界面：带有表情符号的彩色黑客风格界面
- 调试：SQLite中的完整对话历史跟踪
快速开始
先决条件
- Python 3.11+
- 紫外线 （Python包管理器）
- Docker（可选，适用于MCP服务器）
- 无烟煤API键
安装
- 克隆并导航到项目：
cd claude-code-tool- 设置环境变量：
cp .env.example .env
# Edit .env and add your ANTHROPIC_API_KEY- 创建虚拟环境并安装依赖关系：
# uv will automatically create .venv and install dependencies
uv sync- 运行助手：
uv run main.py用法
一旦开始，您将看到一个色彩缤纷的终端界面。尝试以下命令：
基本命令
help - Display help information
tools - List all available tools
exit/quit/q - Exit the assistant查询示例
"Show me the content of main.py"
"What tools do you have?"
"List all Python files in the current directory"
"Run the unit tests"
"Search for 'agent' in the codebase"
"Read the README file"可用工具
本地工具（内置）
- read_file：读取文件内容
- 列表文件：列出目录内容
- write_file：将内容写入文件
- run_pytest：执行pytest测试
- 搜索文件：按模式搜索文件
- 获取_文件_信息：获取详细的文件信息
MCP工具（可选）
要启用MCP工具，您需要安装相应的MCP服务器：
桌面命令器（文件系统操作）
npm install -g @modelcontextprotocol/server-filesystemDuckDuckGo（网络搜索）
npm install -g @modelcontextprotocol/server-duckduckgoGitHub（存储库管理）
npm install -g @modelcontextprotocol/server-github
# Set GITHUB_TOKEN in .env沙盒Python（基于Docker）
# Build the Deno Docker image
docker build -t deno-docker:latest -f ./mcps/deno/Dockerfile ./mcps/deno状态持久化和调试
所有对话都保存在 checkpoints.db。您可以检查状态：
# View recent writes
sqlite3 checkpoints.db "SELECT * FROM writes LIMIT 5"
# View checkpoints
sqlite3 checkpoints.db "SELECT * FROM checkpoints LIMIT 5"配置
环境变量
创建一个 .env 文件包含：
# Required
ANTHROPIC_API_KEY=your_anthropic_api_key
# Optional
GITHUB_TOKEN=your_github_token自定义工具
要添加自定义工具，请编辑 tools/local_tools.py:
from langchain_core.tools import tool
@tool
def my_custom_tool(param: str) -> str:
"""Tool description"""
# Your implementation
return result
# Add to get_local_tools()
def get_local_tools():
return [
# ... existing tools
my_custom_tool,
]项目结构
claude-code-tool/
├── main.py # Entry point
├── agent.py # Core agent implementation
├── tools/
│ ├── __init__.py
│ ├── local_tools.py # Local tool implementations
│ └── mcp_tools.py # MCP tool integration
├── mcps/
│ └── deno/
│ └── Dockerfile # Deno MCP container
├── pyproject.toml # Dependencies
├── .env.example # Environment template
├── .gitignore
└── README.mdUI定制
助理使用 富有的 用于终端UI。在中自定义外观 agent.py:
- 横幅：
_display_welcome() - 颜色：修改样式字符串（例如。，
[bold cyan]) - 面板：调整
Panel()配置
测试
该助手包括pytest集成。测试：
# Ask the assistant
"Run the unit tests"
# Or manually
uv run pytest -v安全考虑
- 文件访问：默认情况下，工具可以访问整个文件系统。考虑限制生产中的访问。
- 代码执行沙盒Python MCP在Docker/Deno中运行以实现隔离。
- API密钥：从不承诺
.env文件夹。使用环境变量。 - 工具权限：审查工具说明并限制敏感操作。
贡献
欢迎投稿！需要改进的地方：
- \[\]为破坏性操作添加人工参与批准
- \[\]对个人笔记（Notion、黑曜石）实施RAG
- \[\]添加更多MCP集成
- \[\]改进错误处理和恢复
- \[\]添加对话导出/导入
- \[\]Web UI界面
运作原理
状态图流
- 用户输入：收集用户查询
- 模型响应：Claude处理输入并决定是否使用工具
- 工具使用 （有条件）：根据要求执行工具
- 循环：返回带有工具结果的模型响应，或返回用户输入
检查点
LangGraph的SQLite检查指针在每个步骤后保存整个对话状态：
- 允许在崩溃后恢复对话
- 便于调试和分析
- 支持多回合上下文保留
MCP集成
模型上下文协议服务器是按需生成的：
- 容器在调用工具时启动
- 进程在执行后终止
- 最小的资源开销
- 清晰地分离关注点
资源
______________________________________________________________________
快乐编码！ 🚀
问题或议题？欢迎打开一个问题或贡献！