Agente de Habilidades Local ToolKit

Un asistente de habilidades local basado en el protocolo MCP (Model Context Protocol), que admite habilidades personalizadas como calculadora, consulta meteorológica, etc., y proporciona una interfaz web y una interfaz API.

Estructura del proyecto

..
├── .env                    # 大模型 API 配置
├── chat_history.db         # SQLite 对话历史数据库（自动生成）
├── index.html              # 前端 Web 界面
├── main.py                 # 主入口（命令行界面）
├── mcp_server.py          # MCP 服务端（核心）
├── server.py               # Flask 后端服务
├── requirements.txt        # 依赖清单
├── README.md               # 项目说明
├── tree.txt                # 目录结构
├── client/                 # 客户端目录
│   ├── doubao_mcp_client.py  # 豆包 API 客户端
│   └── __init__.py
├── config/                 # 配置目录
│   ├── settings.py         # 全局配置
│   └── __init__.py
└── skills/                 # 技能实现目录
    ├── calculator.py       # 计算器技能
    ├── weather.py          # 天气查询技能
    ├── web_search/         # 网络搜索技能目录
    │   └── web_search.py   # DuckDuckGo搜索实现
    |   └── SKILL.md  # skill描述
    |   └── _init_.py   
    └── __init__.py

Related MCP server: MCP Connection Hub

Stack tecnológico

Framework de backend: Python + Flask para construir el servicio web, proporcionando API RESTful e interfaz de salida de streaming SSE.

Protocolo de IA y llamada a modelos: Basado en el SDK compatible con OpenAI para conectarse a la API de modelos grandes, admitiendo la conexión de modelos en formato OpenAI como Doubao.

Protocolo central: MCP (Model Context Protocol) para estandarizar la llamada a herramientas, unificando el registro y la programación de habilidades.

Arquitectura asíncrona: Procesamiento asíncrono con asyncio + aislamiento de pool de hilos, resolviendo el problema de bloqueo de llamadas asíncronas en el entorno síncrono de Flask.

Persistencia de datos: SQLite para el almacenamiento del contexto de diálogo multisesión, admitiendo la gestión de sesiones y la carga de historial.

Plugins de habilidades: Sistema de habilidades modular, que admite la extensión de herramientas conectables como calculadora, clima, búsqueda en red, etc.

Frontend: Interfaz de interacción web implementada con HTML/JS nativo, compatible con renderizado Markdown, efecto de escritura en streaming y visualización de cadena de pensamiento.

Ingeniería: Configuración de variables de API (.env), gestión de dependencias (uv/pip), mecanismos de reintento de errores y degradación, caché de llamadas a herramientas.

Funciones principales

✅ Procesamiento asíncrono estable - Se corrigió el problema de usar asyncio.run() directamente en las rutas de Flask, utilizando un pool de hilos para ejecutar funciones asíncronas.

✅ Persistencia del historial de chat - Uso de SQLite para almacenar el historial de chat, sin pérdida tras el reinicio del servicio, admite gestión multisesión.

✅ Tolerancia a fallos en llamadas a herramientas - Mecanismo de reintento automático, degradación a respuesta directa del modelo cuando falla la llamada a la herramienta.

✅ Caché de herramientas MCP - Caché tras obtener la lista de herramientas por primera vez, reduciendo el costo de inicialización repetida.

✅ Salida en streaming - Interfaz SSE completa implementada, compatible con una experiencia de salida palabra por palabra.

✅ Aviso de llamada a herramientas - Al llamar a una habilidad, se mostrará el mensaje "【Se llamó a la herramienta: {nombre_de_la_herramienta}】".

✅ Soporte multiplataforma - Proporciona tanto interfaz web como interfaz de línea de comandos.

✅ Habilidades enriquecidas - Habilidades integradas de calculadora, consulta meteorológica y búsqueda en red.

✅ Gestión de habilidades - Gestión visual de habilidades en el frontend, permitiendo activar/desactivar habilidades libremente.

✅ Renderizado Markdown - Soporte para respuestas en formato Markdown, resaltado de código, tablas, listas, fórmulas matemáticas, etc.

✅ Visualización de cadena de pensamiento - Visualización plegable del proceso de pensamiento de la IA, facilitando la comprensión de la lógica de razonamiento.

✅ Gestión multisesión - Soporte para crear múltiples diálogos independientes, cada uno guardando su historial por separado.

✅ Carga de historial de chat - Carga automática del historial al cambiar de sesión, registrando completamente el proceso de interacción.

Requisitos del entorno

• Python 3.11+

• openaiSDK(api)

• Herramienta de gestión de paquetes uv (recomendado) o pip

Instalación

Método 1: Usando la herramienta de gestión de paquetes uv (recomendado)

1. Instalar uv

   # Windows
   Set-ExecutionPolicy RemoteSigned -Scope CurrentUser 
   irm https://astral.sh/uv/install.ps1 | iex
   
   # macOS / Linux
   curl -LsSf https://astral.sh/uv/install.sh | sh

2. Clonar el proyecto

   git clone https://github.com/taffy123d/Doubao-MCP-agent
   cd <项目目录>

3. Crear entorno virtual

   uv venv

4. Instalar dependencias

   uv sync

Método 2: Usando pip

1. Clonar el proyecto

   git clone https://github.com/taffy123d/Doubao-MCP-agent
   cd <项目目录>

2. Crear entorno virtual

   python -m venv venv

3. Activar entorno virtual

   # Windows
   venv\Scripts\activate
   
   # macOS / Linux
   source venv/bin/activate

4. Instalar dependencias

   pip install -r requirements.txt

Configuración

• Configurar la clave API en el frontend

• O completar la clave API en el archivo .env:

# OpenAI 兼容格式的 API 配置
OPENAI_API_KEY=你的API密钥
OPENAI_BASE_URL=https://ark.cn-beijing.volces.com/api/v3
OPENAI_MODEL=你的模型ID

Ejecución

Método 1: Inicio completo (recomendado)

uv run server.py
#或者
python server.py

• Acceso al frontend: http://localhost:5000

• Interfaz API: http://localhost:5000/api/*

Método 2: Interfaz de línea de comandos

uv run main.py
#或者
python main.py

• Realizar diálogos directamente en la terminal

• Soporta diálogos multironda y registro histórico

• Escriba clear o 清除历史 para borrar el historial de chat

• Escriba exit, quit o 退出 para salir del programa

Interfaz API

Ejemplo de solicitud API

Interfaz de chat

curl -X POST http://localhost:5000/api/chat \
  -H "Content-Type: application/json" \
  -d '{
    "api_key": "你的API密钥",
    "model": "你的模型ID",
    "base_url": "https://ark.cn-beijing.volces.com/api/v3",
    "message": "北京天气",
    "session_id": "default"
  }'

Interfaz de chat en streaming

curl -X POST http://localhost:5000/api/chat/stream \
  -H "Content-Type: application/json" \
  -d '{
    "api_key": "你的API密钥",
    "model": "你的模型ID",
    "base_url": "https://ark.cn-beijing.volces.com/api/v3",
    "message": "北京天气",
    "session_id": "default"
  }'

Interfaz de borrar historial

curl -X POST http://localhost:5000/api/chat/clear \
  -H "Content-Type: application/json" \
  -d '{
    "session_id": "default"
  }'

Cómo utilizar

Interfaz Web

1. Configurar API

   • Complete la clave API y el ID de Endpoint en el panel de configuración de la izquierda

   • Haga clic en el botón "Probar" para verificar la conexión

2. Chat

   • Ingrese la pregunta en el cuadro de entrada

   • Habilidades admitidas:

     • Calculadora: 计算 123+456

     • Consulta meteorológica: 北京天气

     • Búsqueda en red: 搜索 最新AI新闻

3. Gestión de habilidades

   • Haga clic en "🔧 Gestión de habilidades" a la izquierda para expandir el panel

   • Ver todas las habilidades disponibles y sus descripciones

   • Haga clic en el botón de interruptor para activar/desactivar habilidades

   • Solo se llamarán las habilidades activadas

4. Gestión multisesión

   • Haga clic en "💬 Gestión de diálogos" a la izquierda para expandir el panel

   • Haga clic en "➕ Nuevo diálogo" para crear una nueva sesión

   • Haga clic en el elemento de la lista de sesiones para cambiar a la sesión correspondiente

   • Haga clic en 🗑️ para eliminar sesiones no deseadas

   • Cada sesión guarda su historial de forma independiente

5. Ver resultados

   • El sistema llamará automáticamente a la habilidad correspondiente y devolverá el resultado

   • Soporta respuestas en formato Markdown (resaltado de código, tablas, listas, etc.)

   • Puede hacer clic en "🧠 Proceso de pensamiento" para ver la lógica de razonamiento de la IA

   • Soporta diálogos multironda

Interfaz de línea de comandos

1. Ejecutar programa

   python main.py

2. Ingresar pregunta

   • Ingrese su pregunta directamente en la terminal

   • Habilidades admitidas:

     • Calculadora: 计算 123+456

     • Consulta meteorológica: 北京天气

3. Ver resultados

   • El sistema llamará automáticamente a la habilidad correspondiente y devolverá el resultado

   • Soporta diálogos multironda

   • Escriba clear o 清除历史 para borrar el historial de chat

Cómo añadir nuevas habilidades

Paso 1: Crear archivo de habilidad

Cree un nuevo archivo de habilidad en el directorio skills/, por ejemplo my_skill.py:

"""我的自定义技能"""
from mcp.server.fastmcp import FastMCP

def register_my_skill(mcp: FastMCP):
    """注册技能到 MCP 服务"""
    
    @mcp.tool()
    def my_skill(param1: str, param2: int = 1) -> str:
        """
        我的自定义技能描述
        示例：my_skill(param1="值", param2=2)
        
        Args:
            param1: 参数1描述
            param2: 参数2描述（默认值）
        Returns:
            技能执行结果
        """
        try:
            # 技能逻辑实现
            result = f"处理结果: {param1} - {param2}"
            return result
        except Exception as e:
            return f"处理失败: {str(e)}"

Paso 2: Registrar habilidad

Edite skills/__init__.py y añada la función de registro de la nueva habilidad:

from .calculator import register_calculator_tool
from .weather import register_weather_tool
from .my_skill import register_my_skill

__all__ = [
    "register_calculator_tool", 
    "register_weather_tool",
    "register_my_skill"
]

Paso 3: Actualizar servicio MCP

Edite mcp_server.py y añada el registro de la nueva habilidad:

from skills import register_calculator_tool, register_weather_tool, register_my_skill

# 注册所有技能工具
register_calculator_tool(mcp)
register_weather_tool(mcp)
register_my_skill(mcp)  # 添加这一行

Paso 4: Reiniciar servicio

Reinicie el servicio MCP y el servicio de backend, y la nueva habilidad estará lista para usar.

Especificaciones de desarrollo de habilidades

1. Nombres de archivo: Usar letras minúsculas y guiones bajos

2. Nombres de función: Formato register_xxx_tool

3. Decorador de herramientas: Usar el decorador @mcp.tool()

4. Docstrings: Incluir descripción de la función, ejemplos y explicación de parámetros

5. Manejo de errores: Capturar excepciones y devolver avisos amigables

6. Tipos de parámetros: Usar anotaciones de tipo

Cómo crear una Skill compleja (con SKILL.md)

Para habilidades con funciones más complejas, se recomienda crear un directorio de skill independiente que contenga la implementación de la habilidad y el archivo de descripción SKILL.md.

Estructura de directorios

skills/
└── my_complex_skill/          # skill 目录
    ├── __init__.py            # 导出配置（必选）
    ├── my_skill.py            # 技能实现（必选）
    └── SKILL.md               # skill 描述文档（必选）

Paso 1: Crear directorio de skill y archivo de implementación

Cree un nuevo directorio de skill en el directorio skills/, por ejemplo skills/my_complex_skill/

1.1 Crear archivo de implementación de habilidad my_skill.py

"""我的复杂技能实现"""
from mcp.server.fastmcp import FastMCP
from duckduckgo_search import AsyncDuckDuckGoSearcher  # 示例依赖

def register_my_complex_skill(mcp: FastMCP):
    """注册复杂技能到 MCP 服务"""
    
    @mcp.tool()
    async def my_complex_skill(query: str, limit: int = 5) -> str:
        """
        我的复杂技能描述
        
        Args:
            query: 查询关键词
            limit: 返回结果数量，默认5
        
        Returns:
            格式化的搜索结果
        """
        try:
            async with AsyncDuckDuckGoSearcher() as searcher:
                results = await searcher.atext(query, max_results=limit)
                # 处理并返回结果
                return f"找到 {len(results)} 条结果..."
        except Exception as e:
            return f"搜索失败: {str(e)}"

1.2 Crear __init__.py para exportar configuración

"""my_complex_skill - 我的复杂技能"""
from .my_skill import register_my_complex_skill

__all__ = ["register_my_complex_skill"]

1.3 Crear documento de descripción SKILL.md

# 我的复杂技能

## 功能描述
一句话描述技能功能...

## 使用场景
### ✅ 适用场景
- 场景1
- 场景2

## 参数说明
| 参数 | 类型 | 必填 | 默认值 | 说明 |
|------|------|------|--------|------|
| query | string | 是 | - | 查询关键词 |

## 使用示例
```python
# 示例1
my_complex_skill(query="关键词")

Formato de resultados devueltos

• Resultado 1: xxx

• Resultado 2: xxx

Manejo de excepciones

Notas

1. Nota 1

2. Nota 2

### 步骤 2：更新 skills/__init__.py

```python
from .calculator import register_calculator_tool
from .weather import register_weather_tool
from .web_search import register_web_search_tool
from .my_complex_skill import register_my_complex_skill  # 新增

__all__ = [
    "register_calculator_tool", 
    "register_weather_tool",
    "register_web_search_tool",
    "register_my_complex_skill"  # 新增
]

Paso 3: Actualizar mcp_server.py

from skills import (
    register_calculator_tool, 
    register_weather_tool, 
    register_web_search_tool,
    register_my_complex_skill  # 新增
)

# 注册所有技能工具
register_calculator_tool(mcp)
register_weather_tool(mcp)
register_web_search_tool(mcp)
register_my_complex_skill(mcp)  # 新增

Paso 4: Instalar dependencias adicionales (si es necesario)

Si la nueva skill requiere paquetes de Python adicionales, agréguelos usando uv add o en requirements.txt:

uv add 包名称
或
包名称 >=版本号 #requirements.txt

Luego ejecute:

uv sync
# 或
pip install 包名称

Paso 5: Reiniciar servicio

Reinicie el servicio y la nueva habilidad estará lista para usar.

Especificación SKILL.md

Habilidades de ejemplo

Habilidad de calculadora

• Función: Soporta suma, resta, multiplicación, división, paréntesis y exponenciación

• Llamada: 计算 (10+5)*2

Habilidad de consulta meteorológica

• Función: Consultar el clima de la ciudad y el pronóstico

• Llamada: 上海天气 o 北京天气 3天

Habilidad de búsqueda en red

• Función: Usar DuckDuckGo para buscar las últimas noticias

• Llamada: 搜索 Python最新版本 o 搜索 今天科技新闻

• Dependencia: Librería ddgs (pip install duckduckgo-search)

Aspectos técnicos destacados

1. Optimización de procesamiento asíncrono - Uso de pool de hilos para ejecutar funciones asíncronas, evitando el problema de crear un nuevo bucle de eventos en cada solicitud

2. Persistencia del historial de chat - Almacenamiento persistente basado en SQLite, sin pérdida tras el reinicio del servicio, admite aislamiento multisesión

3. Tolerancia a fallos en llamadas a herramientas - Reintento automático 2 veces en caso de fallo, degradación a respuesta directa del modelo, mejorando la robustez

4. Caché de herramientas MCP - Reducción del costo de inicialización repetida, mejorando la velocidad de respuesta

5. Implementación de salida en streaming - Interfaz SSE completa, proporcionando una mejor experiencia de usuario

6. Aviso de llamada a herramientas - Avisos claros de llamada a herramientas, mejorando la experiencia del usuario

7. Soporte multiplataforma - Proporciona simultáneamente interfaz web e interfaz de línea de comandos

8. Sistema de gestión de habilidades - Gestión visual de habilidades en el frontend, admite activación/desactivación flexible

9. Renderizado Markdown - Soporte completo de Markdown, incluyendo resaltado de código, tablas, etc.

10. Visualización de cadena de pensamiento - Visualización plegable del proceso de razonamiento de la IA

11. Gestión multisesión - Funciones completas de creación, cambio y eliminación de sesiones

12. Carga de historial de chat - Carga y visualización automática del historial de sesiones

Notas

1. Seguridad de la clave API: No envíe la clave API al control de versiones

2. Seguridad de las habilidades: Evite realizar operaciones peligrosas en las habilidades

3. Optimización del rendimiento: Para operaciones que consumen mucho tiempo, considere usar procesamiento asíncrono

4. Manejo de errores: Asegúrese de que las habilidades puedan manejar excepciones de manera elegante

Solución de problemas

• Fallo de conexión: Verifique la clave API y la conexión de red

• La habilidad no responde: Verifique si el servicio MCP se está ejecutando normalmente

• El frontend no se muestra: Verifique si hay errores en la consola del navegador

• Problemas con la interfaz de streaming: Asegúrese de que la conexión de red sea estable, evitando desconexiones a mitad de camino

• Error de base de datos: Verifique los permisos del archivo chat_history.db, asegúrese de que sea legible y escribible

Almacenamiento de datos

El proyecto utiliza una base de datos SQLite para persistir el historial de chat:

• Archivo de base de datos: chat_history.db (directorio raíz del proyecto, generado automáticamente en la primera ejecución)

• Estructura de tabla:

  CREATE TABLE messages (
    id INTEGER PRIMARY KEY AUTOINCREMENT,
    session_id TEXT NOT NULL,    -- 会话ID，支持多会话隔离
    role TEXT NOT NULL,           -- 角色（user/assistant/tool）
    content TEXT NOT NULL,        -- 消息内容
    timestamp DATETIME DEFAULT CURRENT_TIMESTAMP
  )

• Consultar historial: Use herramientas de SQLite o la línea de comandos para ver

  sqlite3 chat_history.db "SELECT * FROM messages ORDER BY timestamp DESC LIMIT 10;"

Sugerencias de expansión

1. Más habilidades: Añadir traducción, consulta de acciones, noticias, etc.

2. Soporte multilingüe: Añadir interfaz multilingüe

3. Optimización de despliegue: Usar despliegue en contenedores Docker

4. Mercado de habilidades: Crear un mercado de habilidades, permitiendo a los usuarios compartir y descargar habilidades

5. Cambio de modelo: Soporte para cambiar entre diferentes modelos de lenguaje grandes

Registro de cambios

2026-03-29 Actualización importante

Actualización del método de llamada API

• httpx → OpenAI SDK: Todas las llamadas API cambiaron de solicitudes HTTP directas con httpx al método SDK openai>=1.0.0

• Renombrado de campos de configuración:

  • DOUBAO_API_KEY → OPENAI_API_KEY

  • DOUBAO_ENDPOINT_ID → OPENAI_MODEL

  • DOUBAO_BASE_URL → OPENAI_BASE_URL (se eliminó el sufijo /chat/completions)

Optimización de llamadas a herramientas

• Limpieza de Schema: Eliminación automática de campos no admitidos por la API de Doubao como title, default, etc.

• Limpieza de Description: Compresión de espacios en blanco innecesarios, optimización de formato

• Conversión de mensajes: Se añadió la función _msg_to_dict() para manejar correctamente el objeto ChatCompletionMessage devuelto por el SDK de OpenAI

• Segunda llamada: Se corrigió el problema de formato de mensaje en la segunda solicitud después de una llamada a herramienta

Corrección de errores

• ✅ Se corrigió el error "Object of type ChatCompletionMessage is not JSON serializable"

• ✅ Se corrigió el problema de conversión de tipos al guardar el historial de mensajes

• ✅ Se añadió un seguimiento detallado de la pila de excepciones para facilitar la depuración

Mejoras de arquitectura

• Se añadió la función auxiliar _msg_to_dict() para unificar la conversión de formato de mensajes

• Se añadió detección de tipo de API (la API de Xunfei omite automáticamente el parámetro tools)

• Optimización del manejo de excepciones y salida de registros de la ruta chat()