Skill MCP Agent

Skills-MCP-Agent-Framework

English | Chinese

______________________________________________________________________

Chinese

An intelligent agent system that supports automatic discovery and integration of MCP servers and skills.

core functionality

Zero configuration extension

• MCP Servers Auto DiscoveryClone MCP Server to mcp-servers/ Directory, Agent automatically recognizes and loads
• Skills hot swappable: In skills/ Directory creation skills folder, available immediately
• No need to modify the codeAdd new tools without modifying the Agent core code or prompt words

Unified tool management

• MCP IntegrationSupports both STDIO and HTTP transmission methods, with persistent connections maintaining session state
• Python SkillsAutomatically generate OpenAI format tool definitions from function signatures and docstrings
• built-in toolsCommon tools for file reading and writing, Bash execution, code editing, etc

Intelligent context management

• Automatic compressionWhen the conversation history exceeds the 50% token limit, the old conversation will be automatically compressed into a structured summary
• long-term memory: Keep the last 10 complete conversations and support multiple rounds of conversations for a long time
• Token budget200K total context, intelligently assigned to system prompts, tool definitions, and conversation history

Tool Search Mechanism

• Load on demandVertical tools (such as Xiaohongshu and YouTube) only load when users query, saving tokens
• BM25 IndexEfficient tool search based on BM25 algorithm
• intelligent matchingSupport multiple query methods such as Chinese alias, English name, tool name, etc

Permission Management System

• fine-grained controlSet different permission policies for different tools
• automatic downgradeDangerous operation automatically downgraded to requiring user confirmation
• configurable: Through permissions.json flexible configuration

How to configure

1. Install dependencies

pip install -r requirements.txt

2. Configure LLM

Set your LLM configuration through environment variables:

export LLM_BASE_URL="https://your-llm-api.com"
export LLM_API_KEY="your-api-key"
export LLM_MODEL_NAME="your-model-name"

Or create .env File (project root directory):

LLM_BASE_URL=https://your-llm-api.com
LLM_API_KEY=your-api-key
LLM_MODEL_NAME=your-model-name

3. Add MCP Servers

Method A: npx remote package (recommended)

mkdir mcp-servers/my-server
cat > mcp-servers/my-server/mcp.config.json  mcp-servers/my-server/mcp.config.json << EOF
{
  "enabled": true,
  "type": "stdio",
  "command": "npx",
  "args": ["-y", "package-name@latest"],
  "env": {},
  "description": "Brief description"
}
EOF

Method B: Clone GitHub Project

cd mcp-servers
git clone https://github.com/xxx/mcp-server my-server
cd my-server
npm install && npm run build

Create mcp.config.json:

{
  "enabled": true,
  "type": "stdio",
  "command": "node",
  "args": ["dist/index.js", "--stdio"],
  "env": {},
  "description": "Brief description"
}

MCP Category Management

Edit mcp-servers/registry.json:

{
  "my-server": {
    "category": "searchable",
    "alias": "My Tool"
  }
}

• core: Resident tools (e.g., playwright, open-websearch)
• searchable: On-demand loading (default)

4. Add Skills

Create skill folders in skills/ directory:

skills/
└── my-skill/
    ├── SKILL.md          # Required: Skill metadata and usage guide
    ├── scripts/          # Optional: Executable scripts
    ├── references/       # Optional: Reference documentation
    └── assets/           # Optional: Templates, icons, etc.

SKILL.md format:

---
name: my-skill
description: Brief description of this skill's functionality and use cases
---

# My Skill

## Usage

Detailed usage instructions...

5. Run Agent

from agent.core.main import Agent

# Initialize Agent
agent = Agent()

# Run conversation
response = agent.run("Help me search for cosmetic recommendations on Xiaohongshu")
print(response)

6. Configure Parameters

Edit agent/core/config.py:

# Context Management
MAX_CONTEXT_TOKENS = 200000      # Total context limit
KEEP_RECENT_TURNS = 10           # Keep recent turns
COMPRESSION_THRESHOLD = 0.5      # Compression threshold

# Tool Execution
MAX_TOOL_RESULT_CHARS = 90000    # Tool result truncation
BASH_TOOL_TIMEOUT = 300          # Bash timeout

# LLM Response
LLM_MAX_TOKENS = 20000           # Default generation tokens

Key Implementation

Architecture Design

Agent Core
├── LLM Client          # LLM API call wrapper
├── Tool Loader         # Unified tool loader
│   ├── MCP Manager     # MCP manager (persistent connection)
│   ├── Skills Loader   # Skills loader
│   └── Built-in Tools  # Built-in tools
├── Context Manager     # Context manager (compression)
├── Permission Manager  # Permission manager
└── BM25 Index          # Tool search index

MCP Integration Flow

1. Scan mcp-servers/ directory
   ↓
2. Identify server type (Node.js/Python/Custom)
   ↓
3. Generate configuration (mcp.config.json)
   ↓
4. FastMCP establishes STDIO connection
   ↓
5. Get tool list (OpenAI format)
   ↓
6. Agent calls tools (persistent session)

Key Files:

• agent/tools/mcp_manager.py - MCP manager implementation
• agent/discovery/mcp_scanner.py - Auto scanner

Context Compression Mechanism

Triggers when conversation history exceeds 50% of available tokens:

History: [Message1, Message2, ..., Message50]
         ↓
Split: [Old: 1-40] + [Recent: 41-50]
         ↓
Call LLM to generate 6-field summary
         ↓
Reassemble: [Summary] + [Recent: 41-50]

Summary Structure:

1. task_timeline - Task timeline
2. tool_deltas - Key tool calls
3. important_files - Important files list
4. current_state - Current state
5. error_memory - Error memory
6. critical_user_intents - Critical user intents

Key Files:

• agent/core/context_manager.py - Context manager implementation

Tool Search Mechanism

Vertical tools load only when user queries relevant topics:

User: "Help me search for cosmetic recommendations on Xiaohongshu"
   ↓
Agent recognizes "Xiaohongshu"
   ↓
Call tool_search("Xiaohongshu")
   ↓
BM25 index match → rednote
   ↓
Dynamically load rednote tools
   ↓
Agent calls rednote tools

Key Files:

• agent/core/tool_loader.py - Tool loader implementation
• agent/core/bm25.py - BM25 index implementation

Skills Design Pattern

Skills use a three-tier loading system:

1. Metadata (name + description) - Always in context (~100 words)
2. SKILL.md body - Loads when skill triggers (\<5k words)
3. Bundled resources - Loads on demand (unlimited)

Progressive Disclosure: Keep SKILL.md concise, separate detailed content into references folder.

Key Files:

• skills/skill-creator/SKILL.md - Skill creation guide

Project Structure

skills-mcp-beta/
├── agent/
│   ├── core/               # Core modules
│   │   ├── main.py         # Agent main orchestration
│   │   ├── llm.py          # LLM client
│   │   ├── tool_loader.py  # Tool loader
│   │   ├── context_manager.py  # Context manager
│   │   ├── permission_manager.py  # Permission manager
│   │   ├── bm25.py         # BM25 index
│   │   └── config.py       # Configuration constants
│   ├── tools/              # Built-in tools
│   │   ├── mcp_manager.py  # MCP manager
│   │   ├── bash_tool.py    # Bash tool
│   │   ├── read_tool.py    # File read
│   │   ├── write_tool.py   # File write
│   │   ├── edit_tool.py    # Code edit
│   │   ├── fetch_tool.py   # Web fetch
│   │   └── ...
│   └── discovery/          # Auto discovery
│       └── mcp_scanner.py  # MCP scanner
│
├── mcp-servers/            # MCP Servers directory
│   ├── registry.json       # MCP category registry
│   ├── playwright/         # Browser automation
│   ├── open-websearch/     # Web search
│   ├── rednote/            # Xiaohongshu
│   └── ...
│
├── skills/                 # Skills directory
│   ├── pdf/                # PDF processing
│   ├── docx/               # Word documents
│   ├── pptx/               # PowerPoint
│   ├── xiaohongshu/        # Xiaohongshu skill
│   ├── skill-creator/      # Skill creation guide
│   └── ...
│
├── docs/                   # Documentation
├── workspace/              # Workspace
│   ├── demo_*.py          # Demo scripts
│   ├── test_*.py          # Test scripts
│   └── logs/              # Log files
│
├── input files/            # Input files directory
├── output files/           # Output files directory
├── temp/                   # Temp files directory
├── requirements.txt        # Python dependencies
└── README.md              # This file

Example Usage

Basic Conversation

from agent.core.main import Agent

agent = Agent()

# Simple query
response = agent.run("What's the weather today?")

# Complex task
response = agent.run("""
Help me complete the following tasks:
1. Search for Python learning notes on Xiaohongshu
2. Summarize the core content of the top 5 notes
3. Generate a study plan document
""")

Using Specific Tools

# Xiaohongshu search
response = agent.run("Search for 'Beijing travel guide' on Xiaohongshu")

# PDF processing
response = agent.run("Read table data from report.pdf")

# Document editing
response = agent.run("Modify the second paragraph of document.docx")

Custom Workspace

from pathlib import Path
from agent.core.main import Agent

agent = Agent(
    workspace_root="/path/to/workspace",
    max_turns=1000,
    task_id="task-123"
)

Summary

Skills-MCP-Agent-Framework is a powerful, easily extensible AI Agent system:

• Zero-Configuration Extension: Add MCP Servers and Skills without modifying core code
• Intelligent Tool Management: Auto-discovery, persistent connections, on-demand loading
• Efficient Context Management: Auto compression, long-term memory, 200K token support
• Flexible Permission System: Fine-grained control, auto downgrade
• Rich Built-in Capabilities: File operations, code editing, web fetching, Bash execution

Suitable for various AI Agent application scenarios, from automated tasks to complex workflow orchestration.

License

MIT License - See LICENSE