Agent with MCP & Skills

💡 项目背景

Claude Code 是 Anthropic 官方推出的强大 AI 编程助手，它让 AI 拥有了文件操作、bash 执行等系统级能力，并支持通过 MCP (Model Context Protocol) 和 Skills 进行功能扩展。然而，现有的开源实现（如 OpenCode）往往过于笨重，难以集成到自己的应用中。

本项目的目标：打造一个轻量级、高度可扩展的 Claude Code 核心能力复刻版本，让开发者能够：

✅ 直接运行独立的 Skills（如文档处理、社媒自动化等）
✅ 轻松集成到自己的 Agent 应用中，赋予 AI 系统级操作能力
✅ 零配置扩展新工具，无需修改代码或提示词

✨ 核心特性

🔧 Claude Code 核心能力复刻

完整实现 Claude Code 的核心工具集：

| 工具类型 | 功能 | 说明 | |---------|------|------| | 文件操作 | Read / Write / Edit | 读取、写入、精确编辑文件 | | 文件搜索 | Glob / Grep | 模式匹配查找文件、正则搜索内容 | | 命令执行 | Bash | 执行 shell 命令、运行脚本 | | MCP 集成 | 自动发现 | 自动扫描并连接 mcp-servers 目录下的所有 MCP 服务器 | | Skills 支持 | 动态加载 | 从 skills 目录自动加载 Python 技能，支持热重载 |

🧠 智能增强特性

智能压缩 - 自动压缩上下文，保持对话历史在 token 限制内
权限系统 - 细粒度控制工具访问权限，支持会话级和持久化配置
Plan + ReAct 框架 - 双层架构：Planner 生成任务计划，Reactor 通过 ReAct 循环执行

🚀 高度可扩展

零配置扩展 - 添加 MCP/Skills 无需修改代码或配置
自动发现 - 自动识别 Node.js、Python、自定义 MCP 服务器
热重载 - 运行时添加新工具，无需重启

📁 项目结构

.
├── agent/
│   ├── core/              # 核心模块
│   │   ├── main.py       # Agent 主类（多轮对话）
│   │   ├── llm.py        # LLM 客户端
│   │   ├── tool_loader.py           # 工具加载器
│   │   └── permission_manager.py     # 权限管理器
│   ├── tools/             # 工具实现
│   │   ├── mcp_manager.py           # MCP 服务器管理
│   │   ├── bash_tool.py             # Bash 执行
│   │   ├── read_tool.py / write_tool.py / edit_tool.py
│   │   ├── glob_tool.py / grep_tool.py
│   │   └── ...
│   └── discovery/         # 自动发现系统
│       └── mcp_scanner.py           # MCP 服务器扫描器
│
├── mcp-servers/          # MCP 服务器目录（自动发现）
├── skills/               # Python 技能目录（自动加载）
└── workspace/            # 工作空间
    ├── demo_*.py        # 演示脚本
    └── test_*.py        # 测试脚本

🚀 快速开始

1. 安装依赖

pip install -r requirements.txt

2. 配置 LLM API

创建 .env 文件：

API_KEY=your_api_key_here
BASE_URL=https://your-api-endpoint
MODEL_NAME=your-model-name  # 可选

或直接修改 agent/core/llm.py 中的配置。

3. 运行演示

# 完整的 Agent 演示（推荐）
python workspace/demo_agent_traverse.py

# 系统测试
python workspace/test_mcp.py

# 查看所有演示
ls workspace/*.py

📦 使用方式

方式 1️⃣：独立运行 Skills

直接运行 skills 目录中的 Python 技能：

# 示例：运行计算器 skill
from skills.calculator.calculator import calculate

result = calculate("2 + 3 * 4")
print(result)  # 输出: 14

可用 Skills：

calculator/ - 数学计算器
Auto-Redbook-Skills/ - 小红书内容自动化（生成笔记、多主题卡片、发布）
skill-creator/ - Skills 创建工具

方式 2️⃣：集成到 Agent 应用

将文件操作、bash 执行等能力集成到你的 AI 应用：

from agent.core.main import Agent

# 创建 Agent 实例（自动加载所有工具）
agent = Agent(
    model_name="your-model",
    enable_permissions=True  # 启用权限系统
)

# 执行任务
response = agent.run(
    goal="读取 README.md 文件并统计单词数",
    max_iterations=10
)
print(response)

Agent 自动拥有：

文件操作能力（read_file, write_file, edit_file）
搜索能力（glob, grep）
命令执行能力（bash）
所有 MCP 工具
所有 Skills

方式 3️⃣：添加 MCP Server

# 方式 A：Git Clone（推荐）
cd mcp-servers
git clone https://github.com/modelcontextprotocol/servers.git
cd servers/src/filesystem && npm install

# 方式 B：自定义配置
# 在 mcp-servers/<your-server>/ 下创建 mcp.config.json

示例配置：

{
  "name": "my-server",
  "command": "node",
  "args": ["dist/index.js"],
  "env": {
    "API_KEY": "${MY_API_KEY}"
  },
  "enabled": true
}

详见 mcp-servers/README.md

方式 4️⃣：添加自定义 Skill

在 skills/ 目录创建 Python 文件：

# skills/my_skill/process.py

def process_data(data: list, operation: str) -> dict:
    """
    处理数据

    Args:
        data: 数据列表
        operation: 操作类型（sum/average/count）

    Returns:
        处理结果字典
    """
    if operation == "sum":
        return {"result": sum(data)}
    elif operation == "average":
        return {"result": sum(data) / len(data)}
    elif operation == "count":
        return {"result": len(data)}
    else:
        return {"error": "Unknown operation"}

无需任何配置，Agent 自动发现并生成工具 schema！

🔐 权限系统

控制 Agent 对敏感操作的访问：

# 配置权限文件 permissions.json
{
  "policies": [
    {
      "name": "allow_read_only",
      "description": "仅允许读取文件",
      "allow": ["read_file", "glob", "grep"],
      "deny": ["write_file", "edit_file", "bash"]
    }
  ],
  "default_policy": "allow_read_only"
}

运行时权限控制：

agent = Agent(enable_permissions=True)

# Agent 调用 write_file 时会提示用户确认
# Agent 调用 read_file 时自动允许

🏗️ 架构设计

Plan + ReAct 双层框架

用户目标: "分析项目文件并生成报告"
    ↓
┌─────────────────────────────────┐
│  Planner（规划器）               │
│  - 理解目标                      │
│  - 生成任务计划                  │
│  - 输出: [任务1, 任务2, 任务3]   │
└─────────────────────────────────┘
    ↓
┌─────────────────────────────────┐
│  Reactor（执行器 - ReAct循环）   │
│                                  │
│  Thought: 我需要先读取文件列表  │
│     ↓                            │
│  Action: call_tool(glob, "**")  │
│     ↓                            │
│  Observation: [file1, file2...] │
│     ↓                            │
│  Thought: 现在读取第一个文件... │
│     ↓                            │
│  ... 循环执行 ...               │
└─────────────────────────────────┘
    ↓
最终输出

智能压缩机制

自动检测上下文长度
保留最近消息和关键信息
压缩历史对话为摘要
保持在 token 限制内（默认 50 轮对话）

MCP 自动发现流程

1. 扫描 mcp-servers/ 目录
   ↓
2. 识别服务器类型
   - Node.js: 检测 package.json
   - Python: 检测 pyproject.toml
   - 自定义: 读取 mcp.config.json
   ↓
3. 生成配置 (.auto-config.json)
   ↓
4. 使用 mcp-use 连接所有服务器
   ↓
5. 获取工具列表（OpenAI function format）
   ↓
6. Agent 自动调用工具

🎯 使用场景

智能编程助手 - 文件读写、代码搜索、命令执行
文档处理自动化 - 批量处理、格式转换、内容分析
社媒内容生成 - 自动生成笔记、卡片、发布（小红书等）
数据分析工具 - 文件解析、数据处理、报告生成
自定义 AI Agent - 集成到你的应用，赋予 AI 系统操作能力

🧪 开发

运行测试

# 完整系统测试
python workspace/test_mcp.py

# Filesystem MCP 测试
python workspace/test_filesystem.py

# 权限系统测试
python workspace/test_permissions.py

查看自动生成的配置

cat .auto-config.json

📚 资源

🆚 对比

| 特性 | 本项目 | OpenCode | Claude Code | |------|-------|----------|-------------| | 轻量级 | ✅ | ❌ 笨重 | ✅ | | 文件操作 | ✅ | ✅ | ✅ | | Bash 执行 | ✅ | ✅ | ✅ | | MCP 集成 | ✅ 自动发现 | ⚠️ 需配置 | ✅ | | Skills 支持 | ✅ 热重载 | ❌ | ✅ | | 权限系统 | ✅ | ❌ | ✅ | | 可集成性 | ✅ 易集成 | ❌ 难集成 | ❌ 闭源 | | 独立运行 Skills | ✅ | ❌ | ❌ |

🤝 贡献

欢迎提交 PR 和 Issues！

本项目灵感来自 Claude Code，致敬 Anthropic 团队的出色工作。

📄 License

MIT

Agent with MCP & Skills

💡 Background

Claude Code is Anthropic's official AI programming assistant that gives AI system-level capabilities like file operations and bash execution, extensible via MCP (Model Context Protocol) and Skills. However, existing open-source implementations (like OpenCode) are often too heavyweight and difficult to integrate into custom applications.

Project Goal: Build a lightweight, highly extensible replication of Claude Code's core capabilities, enabling developers to:

✅ Run standalone Skills directly (document processing, social media automation, etc.)
✅ Easily integrate into custom Agent applications, giving AI system-level operation capabilities
✅ Extend with new tools without code or prompt modifications (zero-config)

✨ Core Features

🔧 Claude Code Core Capabilities Replication

Complete implementation of Claude Code's core toolset:

| Tool Type | Functionality | Description | |-----------|---------------|-------------| | File Operations | Read / Write / Edit | Read, write, and precisely edit files | | File Search | Glob / Grep | Pattern matching for files, regex content search | | Command Execution | Bash | Execute shell commands and scripts | | MCP Integration | Auto-discovery | Automatically scan and connect all MCP servers in mcp-servers directory | | Skills Support | Dynamic loading | Auto-load Python skills from skills directory, supports hot-reload |

🧠 Intelligent Enhancements

Smart Compression - Automatically compress context to keep conversation history within token limits
Permission System - Fine-grained control over tool access, supports session-level and persistent configuration
Plan + ReAct Framework - Dual architecture: Planner generates task plans, Reactor executes via ReAct loop

🚀 Highly Extensible

Zero-Config Extension - Add MCP/Skills without modifying code or configuration
Auto-Discovery - Automatically identify Node.js, Python, and custom MCP servers
Hot-Reload - Add new tools at runtime without restart

📁 Project Structure

.
├── agent/
│   ├── core/              # Core modules
│   │   ├── main.py       # Agent main class (multi-turn conversation)
│   │   ├── llm.py        # LLM client
│   │   ├── tool_loader.py           # Tool loader
│   │   └── permission_manager.py     # Permission manager
│   ├── tools/             # Tool implementations
│   │   ├── mcp_manager.py           # MCP server management
│   │   ├── bash_tool.py             # Bash execution
│   │   ├── read_tool.py / write_tool.py / edit_tool.py
│   │   ├── glob_tool.py / grep_tool.py
│   │   └── ...
│   └── discovery/         # Auto-discovery system
│       └── mcp_scanner.py           # MCP server scanner
│
├── mcp-servers/          # MCP servers directory (auto-discovery)
├── skills/               # Python skills directory (auto-load)
└── workspace/            # Workspace
    ├── demo_*.py        # Demo scripts
    └── test_*.py        # Test scripts

🚀 Quick Start

1. Install Dependencies

pip install -r requirements.txt

2. Configure LLM API

Create .env file:

API_KEY=your_api_key_here
BASE_URL=https://your-api-endpoint
MODEL_NAME=your-model-name  # optional

Or modify configuration in agent/core/llm.py directly.

3. Run Demo

# Complete Agent demo (recommended)
python workspace/demo_agent_traverse.py

# System test
python workspace/test_mcp.py

# View all demos
ls workspace/*.py

📦 Usage

Method 1️⃣: Run Skills Standalone

Directly run Python skills from the skills directory:

# Example: Run calculator skill
from skills.calculator.calculator import calculate

result = calculate("2 + 3 * 4")
print(result)  # Output: 14

Available Skills:

calculator/ - Math calculator
Auto-Redbook-Skills/ - Xiaohongshu (Redbook) content automation (generate notes, multi-theme cards, publishing)
skill-creator/ - Skill creation tool

Method 2️⃣: Integrate into Agent Application

Integrate file operations, bash execution, and more into your AI application:

from agent.core.main import Agent

# Create Agent instance (auto-loads all tools)
agent = Agent(
    model_name="your-model",
    enable_permissions=True  # Enable permission system
)

# Execute task
response = agent.run(
    goal="Read README.md file and count words",
    max_iterations=10
)
print(response)

Agent automatically gains:

File operation capabilities (read_file, write_file, edit_file)
Search capabilities (glob, grep)
Command execution (bash)
All MCP tools
All Skills

Method 3️⃣: Add MCP Server

# Method A: Git Clone (recommended)
cd mcp-servers
git clone https://github.com/modelcontextprotocol/servers.git
cd servers/src/filesystem && npm install

# Method B: Custom configuration
# Create mcp.config.json in mcp-servers/<your-server>/

Example configuration:

{
  "name": "my-server",
  "command": "node",
  "args": ["dist/index.js"],
  "env": {
    "API_KEY": "${MY_API_KEY}"
  },
  "enabled": true
}

See mcp-servers/README.md for details.

Method 4️⃣: Add Custom Skill

Create Python file in skills/ directory:

# skills/my_skill/process.py

def process_data(data: list, operation: str) -> dict:
    """
    Process data

    Args:
        data: Data list
        operation: Operation type (sum/average/count)

    Returns:
        Result dictionary
    """
    if operation == "sum":
        return {"result": sum(data)}
    elif operation == "average":
        return {"result": sum(data) / len(data)}
    elif operation == "count":
        return {"result": len(data)}
    else:
        return {"error": "Unknown operation"}

No configuration needed - Agent automatically discovers and generates tool schema!

🔐 Permission System

Control Agent access to sensitive operations:

# Configure permissions.json
{
  "policies": [
    {
      "name": "allow_read_only",
      "description": "Allow read-only file operations",
      "allow": ["read_file", "glob", "grep"],
      "deny": ["write_file", "edit_file", "bash"]
    }
  ],
  "default_policy": "allow_read_only"
}

Runtime permission control:

agent = Agent(enable_permissions=True)

# Agent prompts user for confirmation when calling write_file
# Agent automatically allows read_file calls

🏗️ Architecture

Plan + ReAct Dual Framework

User Goal: "Analyze project files and generate report"
    ↓
┌─────────────────────────────────┐
│  Planner                         │
│  - Understand goal               │
│  - Generate task plan            │
│  - Output: [Task1, Task2, Task3] │
└─────────────────────────────────┘
    ↓
┌─────────────────────────────────┐
│  Reactor (ReAct Loop)            │
│                                  │
│  Thought: I need to list files  │
│     ↓                            │
│  Action: call_tool(glob, "**")  │
│     ↓                            │
│  Observation: [file1, file2...] │
│     ↓                            │
│  Thought: Now read first file.. │
│     ↓                            │
│  ... loop execution ...         │
└─────────────────────────────────┘
    ↓
Final Output

Smart Compression Mechanism

Auto-detect context length
Preserve recent messages and key information
Compress conversation history into summaries
Stay within token limits (default 50 conversation turns)

MCP Auto-Discovery Flow

1. Scan mcp-servers/ directory
   ↓
2. Identify server types
   - Node.js: detect package.json
   - Python: detect pyproject.toml
   - Custom: read mcp.config.json
   ↓
3. Generate configuration (.auto-config.json)
   ↓
4. Connect all servers using mcp-use
   ↓
5. Get tool list (OpenAI function format)
   ↓
6. Agent automatically invokes tools

🎯 Use Cases

Intelligent Programming Assistant - File read/write, code search, command execution
Document Processing Automation - Batch processing, format conversion, content analysis
Social Media Content Generation - Auto-generate notes, cards, publish (Xiaohongshu, etc.)
Data Analysis Tools - File parsing, data processing, report generation
Custom AI Agents - Integrate into your apps, give AI system operation capabilities

🧪 Development

Run Tests

# Complete system test
python workspace/test_mcp.py

# Filesystem MCP test
python workspace/test_filesystem.py

# Permission system test
python workspace/test_permissions.py

View Auto-Generated Configuration

cat .auto-config.json

📚 Resources

🆚 Comparison

| Feature | This Project | OpenCode | Claude Code | |---------|-------------|----------|-------------| | Lightweight | ✅ | ❌ Heavy | ✅ | | File Operations | ✅ | ✅ | ✅ | | Bash Execution | ✅ | ✅ | ✅ | | MCP Integration | ✅ Auto-discovery | ⚠️ Config needed | ✅ | | Skills Support | ✅ Hot-reload | ❌ | ✅ | | Permission System | ✅ | ❌ | ✅ | | Integrability | ✅ Easy | ❌ Difficult | ❌ Closed-source | | Standalone Skills | ✅ | ❌ | ❌ |

🤝 Contributing

PRs and Issues welcome!

This project is inspired by Claude Code - kudos to the Anthropic team for their excellent work.

📄 License

MIT

Agent with MCP & Skills

💡 项目背景

✨ 核心特性

🔧 Claude Code 核心能力复刻

🧠 智能增强特性

🚀 高度可扩展

📁 项目结构

🚀 快速开始

1. 安装依赖

2. 配置 LLM API

3. 运行演示

📦 使用方式

方式 1️⃣：独立运行 Skills

方式 2️⃣：集成到 Agent 应用

方式 3️⃣：添加 MCP Server

方式 4️⃣：添加自定义 Skill

🔐 权限系统

🏗️ 架构设计

Plan + ReAct 双层框架

智能压缩机制

MCP 自动发现流程

🎯 使用场景

🧪 开发

运行测试

查看自动生成的配置

📚 资源

🆚 对比

🤝 贡献

📄 License

Agent with MCP & Skills

💡 Background

✨ Core Features

🔧 Claude Code Core Capabilities Replication

🧠 Intelligent Enhancements

🚀 Highly Extensible

📁 Project Structure

🚀 Quick Start

1. Install Dependencies

2. Configure LLM API

3. Run Demo

📦 Usage

Method 1️⃣: Run Skills Standalone

Method 2️⃣: Integrate into Agent Application

Method 3️⃣: Add MCP Server

Method 4️⃣: Add Custom Skill

🔐 Permission System

🏗️ Architecture

Plan + ReAct Dual Framework

Smart Compression Mechanism

MCP Auto-Discovery Flow

🎯 Use Cases

🧪 Development

Run Tests

View Auto-Generated Configuration

📚 Resources

🆚 Comparison

🤝 Contributing

📄 License

Install Package (if required)

Cursor configuration (mcp.json)