ToolKit 로컬 스킬 에이전트

MCP(Model Context Protocol) 프로토콜 기반의 로컬 스킬 어시스턴트로, 계산기, 날씨 조회 등 커스텀 스킬을 지원하며 웹 인터페이스와 API 인터페이스를 제공합니다.

프로젝트 구조

..
├── .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

기술 스택

백엔드 프레임워크: Python + Flask로 웹 서비스 구축, RESTful API 및 SSE 스트리밍 출력 인터페이스 제공

AI 프로토콜 및 모델 호출: OpenAI 호환 SDK를 기반으로 대규모 모델 API 연동, Doubao 등 OpenAI 형식 모델 접속 지원

핵심 프로토콜: MCP(Model Context Protocol)를 통한 도구 호출 표준화, 스킬 등록 및 스케줄링 통합

비동기 아키텍처: asyncio 비동기 처리 + 스레드 풀 격리, Flask 동기 환경에서의 비동기 호출 차단 문제 해결

데이터 영속성: SQLite를 통한 다중 세션 대화 컨텍스트 저장, 세션 관리 및 기록 로드 지원

스킬 플러그인화: 모듈식 스킬 시스템, 계산기, 날씨, 웹 검색 등 플러그인 방식의 도구 확장 지원

프론트엔드: 네이티브 HTML/JS로 구현된 웹 인터페이스, Markdown 렌더링, 스트리밍 타이핑 효과, 사고 과정(Chain of Thought) 표시 지원

엔지니어링: API 변수 설정(.env), 의존성 관리(uv/pip), 오류 재시도 및 성능 저하 방지 메커니즘, 도구 호출 캐싱

핵심 기능

✅ 안정적인 비동기 처리 - Flask 라우트에서 직접 asyncio.run()을 사용하는 문제를 수정하고, 스레드 풀을 사용하여 비동기 함수 실행

✅ 대화 기록 영속성 - SQLite를 사용하여 대화 기록 저장, 서비스 재시작 시에도 유지되며 다중 세션 관리 지원

✅ 도구 호출 내결함성 - 자동 재시도 메커니즘, 도구 호출 실패 시 모델이 직접 답변하도록 대체

✅ MCP 도구 캐싱 - 도구 목록을 처음 가져온 후 캐싱하여 반복적인 초기화 오버헤드 감소

✅ 스트리밍 출력 - 완전한 SSE 스트리밍 인터페이스 구현, 글자 단위 출력 경험 지원

✅ 도구 호출 알림 - 스킬 호출 시 "【도구 호출: {도구 이름}】" 알림 메시지 표시

✅ 멀티 플랫폼 지원 - 웹 인터페이스와 명령줄 인터페이스(CLI) 두 가지 상호작용 방식 제공

✅ 풍부한 스킬 - 계산기, 날씨 조회 및 웹 검색 스킬 내장

✅ 스킬 관리 - 프론트엔드 시각화 스킬 관리, 자유로운 스킬 활성화/비활성화

✅ Markdown 렌더링 - Markdown 형식의 답변 지원, 코드 하이라이팅, 표, 목록, 수학 공식 등 지원

✅ 사고 과정 표시 - 접기/펼치기가 가능한 AI 사고 과정 표시, 추론 논리 이해 용이

✅ 다중 세션 관리 - 여러 개의 독립적인 대화 생성 지원, 각 대화별 기록 독립적 저장

✅ 대화 기록 로드 - 세션 전환 시 대화 기록 자동 로드, 상호작용 과정 전체 기록

환경 요구 사항

• Python 3.11+

• openaiSDK(api)

• uv 패키지 관리 도구(권장) 또는 pip

설치

방법 1: uv 패키지 관리 도구 사용(권장)

1. 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. 프로젝트 복제

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

3. 가상 환경 생성

   uv venv

4. 의존성 설치

   uv sync

방법 2: pip 사용

1. 프로젝트 복제

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

2. 가상 환경 생성

   python -m venv venv

3. 가상 환경 활성화

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

4. 의존성 설치

   pip install -r requirements.txt

설정

• 프론트엔드에서 API 키 설정

• 또는 .env 파일에 API 키 입력:

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

실행

방법 1: 전체 시작(권장)

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

• 프론트엔드 접속: http://localhost:5000

• API 인터페이스: http://localhost:5000/api/*

방법 2: 명령줄 인터페이스(CLI)

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

• 터미널에서 직접 대화 진행

• 다중 대화 및 기록 지원

• clear 또는 清除历史 입력 시 대화 기록 삭제

• exit, quit 또는 退出 입력 시 프로그램 종료

API 인터페이스

API 요청 예시

채팅 인터페이스

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"
  }'

스트리밍 채팅 인터페이스

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"
  }'

기록 삭제 인터페이스

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

사용 방법

웹 인터페이스

1. API 설정

   • 왼쪽 설정 패널에 API Key와 Endpoint ID 입력

   • 「테스트」 버튼을 클릭하여 연결 확인

2. 채팅

   • 입력창에 질문 입력

   • 지원 스킬:

     • 계산기: 计算 123+456

     • 날씨 조회: 北京天气

     • 웹 검색: 搜索 最新AI新闻

3. 스킬 관리

   • 왼쪽 「🔧 스킬 관리」 클릭하여 패널 확장

   • 사용 가능한 모든 스킬과 설명 확인

   • 스위치 버튼을 클릭하여 스킬 활성화/비활성화

   • 활성화된 스킬만 호출됨

4. 다중 세션 관리

   • 왼쪽 「💬 대화 관리」 클릭하여 패널 확장

   • 「➕ 새 대화」 클릭하여 새 세션 생성

   • 세션 목록 항목을 클릭하여 해당 대화로 전환

   • 🗑️를 클릭하여 불필요한 대화 삭제

   • 각 세션은 기록을 독립적으로 저장

5. 결과 확인

   • 시스템이 자동으로 해당 스킬을 호출하여 결과 반환

   • Markdown 형식의 답변 지원(코드 하이라이팅, 표, 목록 등)

   • 「🧠 사고 과정」을 클릭하여 AI의 추론 논리 확인 가능

   • 다중 대화 지원

명령줄 인터페이스(CLI)

1. 프로그램 실행

   python main.py

2. 질문 입력

   • 터미널에 직접 질문 입력

   • 지원 스킬:

     • 계산기: 计算 123+456

     • 날씨 조회: 北京天气

3. 결과 확인

   • 시스템이 자동으로 해당 스킬을 호출하여 결과 반환

   • 다중 대화 지원

   • clear 또는 清除历史 입력 시 대화 기록 삭제

새 스킬 추가 방법

1단계: 스킬 파일 생성

skills/ 디렉토리에 새 스킬 파일(예: 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)}"

2단계: 스킬 등록

skills/__init__.py를 편집하여 새 스킬 등록 함수 추가:

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"
]

3단계: MCP 서비스 업데이트

mcp_server.py를 편집하여 새 스킬 등록 추가:

from skills import register_calculator_tool, register_weather_tool, register_my_skill

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

4단계: 서비스 재시작

MCP 서비스와 백엔드 서비스를 재시작하면 새 스킬을 사용할 수 있습니다.

스킬 개발 규격

1. 파일 명명: 소문자와 밑줄 사용

2. 함수 명명: register_xxx_tool 형식

3. 도구 데코레이터: @mcp.tool() 사용

4. 독스트링(Docstring): 기능 설명, 예시 및 매개변수 설명 포함

5. 오류 처리: 예외를 포착하고 친절한 메시지 반환

6. 매개변수 타입: 타입 어노테이션 사용

복잡한 스킬 생성 방법(SKILL.md 포함)

기능이 복잡한 스킬의 경우, 스킬 구현과 SKILL.md 설명 파일이 포함된 독립적인 스킬 디렉토리를 생성하는 것이 좋습니다.

디렉토리 구조

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

1단계: 스킬 디렉토리 및 구현 파일 생성

skills/ 디렉토리에 새 스킬 디렉토리(예: skills/my_complex_skill/) 생성

1.1 스킬 구현 파일 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 __init__.py 생성 및 설정 내보내기

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

__all__ = ["register_my_complex_skill"]

1.3 SKILL.md 설명 문서 생성

# 我的复杂技能

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

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

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

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

결과 반환 형식

• 결과 1: xxx

• 결과 2: xxx

예외 처리

주의 사항

1. 주의 사항 1

2. 주의 사항 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"  # 新增
]

3단계: 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)  # 新增

4단계: 추가 의존성 설치(필요 시)

새 스킬에 추가 Python 패키지가 필요한 경우, uv add로 가져오거나 requirements.txt에 추가:

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

그 후 실행:

uv sync
# 或
pip install 包名称

5단계: 서비스 재시작

서비스를 재시작하면 새 스킬을 사용할 수 있습니다.

SKILL.md 규격

스킬 예시

계산기 스킬

• 기능: 사칙연산, 괄호, 거듭제곱 연산 지원

• 호출: 计算 (10+5)*2

날씨 조회 스킬

• 기능: 도시 날씨 및 예보 조회

• 호출: 上海天气 또는 北京天气 3天

웹 검색 스킬

• 기능: DuckDuckGo를 사용하여 최신 정보 검색

• 호출: 搜索 Python最新版本 또는 搜索 今天科技新闻

• 의존성: ddgs 라이브러리(pip install duckduckgo-search)

기술적 하이라이트

1. 비동기 처리 최적화 - 스레드 풀을 사용하여 비동기 함수 실행, 요청마다 새 이벤트 루프를 생성하는 문제 방지

2. 대화 기록 영속성 - SQLite 기반의 영속적 저장, 서비스 재시작 시 유지, 다중 세션 격리 지원

3. 도구 호출 내결함성 - 실패 시 2회 자동 재시도, 모델 직접 답변으로 대체하여 견고성 향상

4. MCP 도구 캐싱 - 반복적인 초기화 오버헤드 감소, 응답 속도 향상

5. 스트리밍 출력 구현 - 완전한 SSE 스트리밍 인터페이스, 더 나은 사용자 경험 제공

6. 도구 호출 알림 - 명확한 도구 호출 알림으로 사용자 경험 향상

7. 멀티 플랫폼 지원 - 웹 인터페이스와 명령줄 인터페이스 동시 제공

8. 스킬 관리 시스템 - 프론트엔드 시각화 스킬 관리, 유연한 활성화/비활성화 지원

9. Markdown 렌더링 - 코드 하이라이팅, 표 등을 포함한 완전한 Markdown 지원

10. 사고 과정 표시 - 접기/펼치기가 가능한 AI 추론 과정 표시

11. 다중 세션 관리 - 완전한 세션 생성, 전환, 삭제 기능

12. 대화 기록 로드 - 세션 기록 자동 로드 및 표시

주의 사항

1. API 키 보안: API 키를 버전 관리 시스템에 커밋하지 마십시오.

2. 스킬 보안: 스킬 내에서 위험한 작업을 수행하지 마십시오.

3. 성능 최적화: 시간이 오래 걸리는 작업은 비동기 처리를 고려하십시오.

4. 오류 처리: 스킬이 예외 상황을 우아하게 처리할 수 있도록 하십시오.

문제 해결

• 연결 실패: API 키와 네트워크 연결 확인

• 스킬 응답 없음: MCP 서비스가 정상적으로 실행 중인지 확인

• 프론트엔드 미표시: 브라우저 콘솔에 오류가 있는지 확인

• 스트리밍 인터페이스 문제: 네트워크 연결이 안정적인지 확인하고 중간에 끊기지 않도록 주의

• 데이터베이스 오류: chat_history.db 파일 권한을 확인하여 읽기/쓰기 가능 여부 확인

데이터 저장

프로젝트는 SQLite 데이터베이스를 사용하여 대화 기록을 영속화합니다:

• 데이터베이스 파일: chat_history.db(프로젝트 루트 디렉토리, 최초 실행 시 자동 생성)

• 테이블 구조:

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
)

• 기록 조회: SQLite 도구 또는 명령줄을 사용하여 확인

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

확장 제안

1. 더 많은 스킬: 번역, 주식 조회, 뉴스 등 스킬 추가

2. 다국어 지원: 다국어 인터페이스 추가

3. 배포 최적화: Docker 컨테이너화 배포

4. 스킬 마켓: 스킬 마켓을 생성하여 사용자가 스킬을 공유하고 다운로드할 수 있도록 지원

5. 모델 전환: 다양한 대규모 언어 모델 간 전환 지원

업데이트 로그

2026-03-29 주요 업데이트

API 호출 방식 업그레이드

• httpx → OpenAI SDK: 모든 API 호출을 httpx 직접 HTTP 요청에서 openai>=1.0.0 SDK 방식으로 변경

• 설정 필드 이름 변경:

  • DOUBAO_API_KEY → OPENAI_API_KEY

  • DOUBAO_ENDPOINT_ID → OPENAI_MODEL

  • DOUBAO_BASE_URL → OPENAI_BASE_URL(/chat/completions 접미사 제거)

도구 호출 최적화

• Schema 정리: Doubao API에서 지원하지 않는 title, default 등의 필드 자동 제거

• Description 정리: 불필요한 공백 문자 압축, 형식 최적화

• 메시지 변환: _msg_to_dict() 함수 추가, OpenAI SDK가 반환하는 ChatCompletionMessage 객체를 올바르게 처리

• 2차 호출: 도구 호출 후 2차 요청 시 메시지 형식 문제 수정

버그 수정

• ✅ "Object of type ChatCompletionMessage is not JSON serializable" 오류 수정

• ✅ 메시지 기록 저장 시 타입 변환 문제 수정

• ✅ 디버깅을 위한 상세 예외 스택 추적 추가

아키텍처 개선

• _msg_to_dict() 보조 함수 추가, 메시지 형식 변환 통합

• API 타입 감지 추가(Xunfei API는 tools 매개변수 자동 건너뜀)

• chat() 라우트의 예외 처리 및 로그 출력 최적화