AI导哈

智能Agent集成框架

一个支持MCP Servers和Skills自动发现与集成的智能Agent系统，具备零配置扩展、统一工具管理、智能上下文管理等功能。

  • by tianyiwang630-ship-it
  • Python
  • 本地部署
  • 4 星标
  • 更新于
在 GitHub 查看 tianyiwang630-ship-it/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 << EOF
{
  "enabled": true,
  "type": "stdio",
  "command": "npx",
  "args": ["-y", "package-name@latest"],
  "env": {},
  "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": "简要说明"
}

MCP classification management

edit mcp-servers/registry.json Set tool classification:

{
  "my-server": {
    "category": "searchable",
    "alias": "我的工具"
  }
}
  • coreResident tools (such as playwright, open web search)
  • searchableOn demand loading (default)

4. Add Skills

In skills/ Directory creation skills folder:

skills/
└── my-skill/
    ├── SKILL.md          # 必需：技能元数据和使用指南
    ├── scripts/          # 可选：可执行脚本
    ├── references/       # 可选：参考文档
    └── assets/           # 可选：模板、图标等资源

SKILL.md Format

---
name: my-skill
description: 简要描述这个技能的功能和使用场景
---

# My Skill

## 使用方法

具体的使用说明...

5. Run the Agent

from agent.core.main import Agent

# 初始化 Agent
agent = Agent()

# 运行对话
response = agent.run("帮我搜索小红书上的化妆品推荐")
print(response)

6. Configure parameters

edit agent/core/config.py Adjust configuration:

# 上下文管理
MAX_CONTEXT_TOKENS = 200000      # 总上下文限制
KEEP_RECENT_TURNS = 10           # 保留最近轮次
COMPRESSION_THRESHOLD = 0.5      # 压缩阈值

# 工具执行
MAX_TOOL_RESULT_CHARS = 90000    # 工具结果截断
BASH_TOOL_TIMEOUT = 300          # Bash 超时时间

# LLM 响应
LLM_MAX_TOKENS = 20000           # 默认生成 token 数

Key implementation

Architectural Design

Agent Core
├── LLM Client          # LLM API 调用封装
├── Tool Loader         # 统一工具加载器
│   ├── MCP Manager     # MCP 管理器（持久连接）
│   ├── Skills Loader   # Skills 加载器
│   └── Built-in Tools  # 内置工具
├── Context Manager     # 上下文管理器（压缩）
├── Permission Manager  # 权限管理器
└── BM25 Index          # 工具搜索索引

MCP Integration Process

1. 扫描 mcp-servers/ 目录
   ↓
2. 识别 server 类型（Node.js/Python/自定义）
   ↓
3. 生成配置（mcp.config.json）
   ↓
4. FastMCP 建立 STDIO 连接
   ↓
5. 获取工具列表（OpenAI format）
   ↓
6. Agent 调用工具（持久会话）

key document：

Context compression mechanism

When the conversation history exceeds 50% of the available tokens, compression is triggered:

History: [消息1, 消息2, ..., 消息50]
         ↓
分离: [旧消息: 1-40] + [最近: 41-50]
         ↓
调用 LLM 生成 6 字段摘要
         ↓
重组: [摘要消息] + [最近: 41-50]

Abstract Structure：

  1. task_timeline -Task timeline
  2. tool_deltas -Key tool call
  3. important_files -List of Important Documents
  4. current_state -Current Status
  5. error_memory -Wrong memory
  6. critical_user_intents -Key user intent

key document：

Tool Search Mechanism

The vertical tool only loads when the user queries:

用户: "帮我搜一下小红书上的化妆品推荐"
   ↓
Agent 识别到 "小红书"
   ↓
调用 tool_search("小红书")
   ↓
BM25 索引匹配 → rednote
   ↓
动态加载 rednote 工具
   ↓
Agent 调用 rednote 工具

key document：

Skills design pattern

Skills uses a three-tier loading system:

  1. metadata(name+description) - Always in context (~100 words)
  2. SKILL.md Subject -Load when skill is triggered (<5k words)
  3. resource bundles -Load on demand (unlimited)

progressive disclosureKeep SKILL.md concise and separate detailed content into the references folder.

key document：

project structure

skills-mcp-beta/
├── agent/
│   ├── core/               # 核心模块
│   │   ├── main.py         # Agent 主编排
│   │   ├── llm.py          # LLM 客户端
│   │   ├── tool_loader.py  # 工具加载器
│   │   ├── context_manager.py  # 上下文管理器
│   │   ├── permission_manager.py  # 权限管理器
│   │   ├── bm25.py         # BM25 索引
│   │   └── config.py       # 配置常量
│   ├── tools/              # 内置工具
│   │   ├── mcp_manager.py  # MCP 管理器
│   │   ├── bash_tool.py    # Bash 工具
│   │   ├── read_tool.py    # 文件读取
│   │   ├── write_tool.py   # 文件写入
│   │   ├── edit_tool.py    # 代码编辑
│   │   ├── fetch_tool.py   # 网页抓取
│   │   └── ...
│   └── discovery/          # 自动发现
│       └── mcp_scanner.py  # MCP 扫描器
│
├── mcp-servers/            # MCP Servers 目录
│   ├── registry.json       # MCP 分类注册表
│   ├── playwright/         # 浏览器自动化
│   ├── open-websearch/     # 网页搜索
│   ├── rednote/            # 小红书
│   └── ...
│
├── skills/                 # Skills 目录
│   ├── pdf/                # PDF 处理
│   ├── docx/               # Word 文档
│   ├── pptx/               # PowerPoint
│   ├── xiaohongshu/        # 小红书技能
│   ├── skill-creator/      # 技能创建指南
│   └── ...
│
├── docs/                   # 文档
├── workspace/              # 工作空间
│   ├── demo_*.py          # 演示脚本
│   ├── test_*.py          # 测试脚本
│   └── logs/              # 日志文件
│
├── input files/            # 输入文件目录
├── output files/           # 输出文件目录
├── temp/                   # 临时文件目录
├── requirements.txt        # Python 依赖
└── README.md              # 本文件

Example usage

Basic Dialogue

from agent.core.main import Agent

agent = Agent()

# 简单查询
response = agent.run("今天天气怎么样？")

# 复杂任务
response = agent.run("""
帮我完成以下任务：
1. 搜索小红书上关于 Python 学习的笔记
2. 总结前 5 篇笔记的核心内容
3. 生成一份学习计划文档
""")

Using specific tools

# 小红书搜索
response = agent.run("在小红书搜索'北京旅游攻略'")

# PDF 处理
response = agent.run("读取 report.pdf 中的表格数据")

# 文档编辑
response = agent.run("修改 document.docx 的第二段")

Customize 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 and easily scalable AI Agent system:

  • Zero configuration extensionAdd MCP Servers and Skills without modifying the core code
  • Intelligent tool managementAuto discovery, persistent connection, on-demand loading
  • Efficient context management: Automatic compression, long-term memory, 200K token support
  • Flexible permission systemFine grained control, automatic downgrade
  • Rich built-in capabilities: File manipulation, code editing, web crawling, Bash execution

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

license

MIT License - see details LICENSE

English

An intelligent Agent system with automatic discovery and integration of MCP Servers and Skills.

Core Features

Zero-Configuration Extension

  • MCP Servers Auto-Discovery: Clone MCP Servers to mcp-servers/ directory, Agent automatically recognizes and loads them
  • Skills Hot-Swap: Create skill folders in skills/ directory, immediately available
  • No Code Modification: Adding new tools requires no changes to Agent core code or prompts

Unified Tool Management

  • MCP Integration: Supports both STDIO and HTTP transports with persistent connections
  • Python Skills: Automatically generates OpenAI format tool definitions from function signatures and docstrings
  • Built-in Tools: File read/write, Bash execution, code editing, and more

Intelligent Context Management

  • Auto Compression: When conversation history exceeds 50% token limit, automatically compresses old conversations into structured summaries
  • Long-term Memory: Preserves the most recent 10 complete turns for extended multi-turn conversations
  • Token Budget: 200K total context with intelligent allocation for system prompts, tool definitions, and conversation history

Tool Search Mechanism

  • On-Demand Loading: Vertical tools (like Xiaohongshu, YouTube) load only when user queries relevant topics, saving tokens
  • BM25 Indexing: Efficient tool search based on BM25 algorithm
  • Smart Matching: Supports Chinese aliases, English names, tool names, and various query methods

Permission Management System

  • Fine-grained Control: Set different permission policies for different tools
  • Auto Downgrade: Dangerous operations automatically downgrade to require user confirmation
  • Configurable: Flexible configuration via permissions.json

Configuration

1. Install Dependencies

pip install -r requirements.txt

2. Configure LLM

Set via 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 in project root:

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 << 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:

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:

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:

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:

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

相关 MCP