nexus-agent-platform 0.1.0

AI agent platform with MCP tool integration

Nexus Agent Platform

MCP(Model Context Protocol) + Agent Skills 기반 범용 AI Agent 플랫폼. MCP 서버와 Agent Skills를 등록·관리하고, Custom Pages로 HTML 도구와 URL 북마크를 폴더 트리로 정리하며, LLM이 모든 도구와 스킬을 활용하여 사용자 요청에 응답합니다.

아키텍처

User → ChatInterface (React) → POST /api/chat/ → AgentOrchestrator
  → system prompt에 <available_skills> XML 주입
  → MCP tools + skill tools 병합
  → LLMClient (LiteLLM) → Gemini API
  → tool_calls 라우팅:
      → skill tool (read_skill, run_skill_script, read_skill_reference)
          → SkillManager → backend/skills/*/SKILL.md
      → namespaced tool (server__tool)
          → MCPClientManager → MCP Server (stdio/sse/streamable-http)
  → Tool 결과를 메시지에 추가 → 2차 LLM 호출
  → 최종 응답 → ChatInterface

주요 기능

Chat

• Gemini 기반 AI 채팅 (LiteLLM 추상화)
• 이미지 첨부 지원 (base64 인코딩)
• MCP 도구 + Agent Skills 자동 라우팅
• 커스텀 배경 이미지 (배율/위치/투명도 조정, 드래그 위치 변경)

MCP Servers (/tools)

• MCP 서버 등록/연결/재시작/삭제
• stdio, SSE, streamable-http 전송 지원
• 서버별 도구 목록 자동 탐색
• 연결 상태 실시간 모니터링 및 토글

Agent Skills (/skills)

• SKILL.md 기반 스킬 정의 (YAML frontmatter + Markdown 지시사항)
• 스킬 내 스크립트 실행 (Python, Shell, JS)
• 스킬 내 참조 문서 로드
• ZIP 업로드 및 로컬 경로 임포트 지원

Custom Pages (/pages)

• HTML 파일 업로드 및 뷰어
• URL 북마크 등록 (iframe 지원 여부 자동 체크)
• 폴더 트리 구조로 정리 (생성/이름변경/삭제)
• 브레드크럼 네비게이션

Settings (/settings)

• 테마 커스터마이징: 액센트 컬러(6종), 다크/라이트 모드, 배경 톤
• 채팅 배경 이미지: 프리셋 선택, 커스텀 업로드, 배율/위치/투명도 조정
• LLM 설정: 모델 선택, API 키, 온도, 최대 토큰, 시스템 프롬프트
• 사용자 프로필: 이름, 아바타
• 백엔드 연결 상태 확인

기술 스택

계층	기술
Frontend	Next.js 16, React 19, TypeScript, Tailwind CSS, shadcn/ui
Backend	Python 3.13, FastAPI, Pydantic
LLM	Google Gemini 3 Flash Preview (LiteLLM 추상화)
Tool System	MCP (Model Context Protocol) + Agent Skills
패키지 매니저	pnpm (Frontend), uv (Backend)

프로젝트 구조

track_platform/
├── backend/
│   ├── app/
│   │   ├── api/endpoints/         # API 라우터 (chat, mcp, skills, pages, settings)
│   │   ├── core/                  # 핵심 로직
│   │   │   ├── agent.py           # AgentOrchestrator (도구 라우팅)
│   │   │   ├── llm.py             # LLMClient (LiteLLM 래퍼)
│   │   │   ├── mcp_manager.py     # MCP 서버 연결 관리
│   │   │   ├── skill_manager.py   # Agent Skills 관리
│   │   │   ├── page_manager.py    # Pages 폴더 트리 관리
│   │   │   └── settings_manager.py # LLM 설정 관리
│   │   └── models/                # Pydantic 데이터 모델
│   ├── skills/                    # Agent Skills 저장 디렉토리
│   ├── pages/                     # 업로드된 HTML 저장 디렉토리
│   ├── mcp.json                   # MCP 서버 설정 (자동 생성)
│   ├── skills.json                # 스킬 활성화 상태 (자동 생성)
│   ├── pages.json                 # 페이지 메타데이터 (자동 생성)
│   ├── settings.json              # LLM 설정 (자동 생성)
│   ├── .env                       # 환경 변수 (GOOGLE_API_KEY 등)
│   └── .env.example               # 환경 변수 템플릿
├── frontend/
│   ├── src/
│   │   ├── app/                   # 페이지 (chat, tools, skills, pages, settings)
│   │   ├── components/            # UI 컴포넌트
│   │   └── lib/
│   │       ├── config.ts          # API_BASE_URL 중앙 설정
│   │       ├── api/               # API 클라이언트 (mcp, skills, pages, settings)
│   │       └── stores/            # 클라이언트 상태 (theme, profile)
│   └── package.json
└── CLAUDE.md

빠른 시작

1. Backend

cd backend
cp .env.example .env     # GOOGLE_API_KEY 설정
uv sync
uv run uvicorn app.main:app --reload --host 0.0.0.0 --port 8000

2. Frontend

cd frontend
pnpm install
pnpm dev

기본적으로 http://localhost:8000의 백엔드에 연결됩니다. 백엔드 주소가 다르면 frontend/.env.local을 생성하세요:

# frontend/.env.local (필요할 때만 생성)
NEXT_PUBLIC_API_URL=http://192.168.0.100:8000

로컬 개발(localhost:8000)이면 이 파일 없이 동작합니다.

3. MCP 서버 등록

프론트엔드 MCP Servers 대시보드(/tools)에서 등록하거나, backend/mcp.json에 직접 추가합니다.

{
  "mcpServers": {
    "example": {
      "transport": "stdio",
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-everything"],
      "enabled": true
    }
  }
}

4. Agent Skill 등록

프론트엔드 Agent Skills 대시보드(/skills)에서 등록하거나, backend/skills/ 디렉토리에 스킬 폴더를 생성합니다. ZIP 업로드 및 로컬 경로 임포트도 지원됩니다.

backend/skills/
└── my-skill/
    ├── SKILL.md            # 필수: YAML frontmatter + 지시사항
    ├── scripts/            # 선택: 실행 스크립트 (.py, .sh, .js)
    └── references/         # 선택: 참조 문서

SKILL.md 예시:

---
name: my-skill
description: >
  이 스킬이 하는 일과 언제 사용해야 하는지 설명합니다.
---

# My Skill

## 사용 방법

1. 사용자가 관련 질문을 하면 이 스킬이 활성화됩니다
2. scripts/ 에 있는 스크립트를 실행할 수 있습니다
3. references/ 에 있는 문서를 참조할 수 있습니다

5. Custom Pages 등록

프론트엔드 Custom Pages 대시보드(/pages)에서 관리합니다.

• HTML 파일 업로드: 정적 HTML 페이지 등록 및 뷰어
• URL 북마크: 외부 URL 등록 (iframe 지원 여부 자동 체크)
• 폴더: 페이지들을 트리 구조로 분류
• 로컬 경로 임포트: 서버 파일 시스템에서 직접 임포트

환경 변수

Backend (backend/.env)

변수	필수	기본값	설명
GOOGLE_API_KEY	O	—	Gemini API 키
LITELLM_MODEL	O	gemini/gemini-3-flash-preview	LLM 모델 이름
LITELLM_BASE_URL	X	—	커스텀 LLM 엔드포인트

Frontend (frontend/.env.local)

변수	필수	기본값	설명
NEXT_PUBLIC_API_URL	X	http://localhost:8000	백엔드 API 주소

프론트엔드는 .env.local 파일이 없으면 기본값(http://localhost:8000)을 사용합니다.

포트

서비스	URL
Frontend	http://localhost:3000
Backend API	http://localhost:8000
Swagger Docs	http://localhost:8000/docs