Metadata-Version: 2.4
Name: nexus-agent-platform
Version: 0.1.0
Summary: AI agent platform with MCP tool integration
Project-URL: Homepage, https://github.com/EJCHO-salary/track_platform
Project-URL: Repository, https://github.com/EJCHO-salary/track_platform
License-Expression: MIT
Keywords: agent,ai,chatbot,gemini,llm,mcp
Classifier: Development Status :: 3 - Alpha
Classifier: Environment :: Console
Classifier: Environment :: Web Environment
Classifier: Framework :: FastAPI
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Requires-Python: >=3.13
Requires-Dist: click>=8.0
Requires-Dist: fastapi>=0.128.8
Requires-Dist: google-generativeai>=0.8.6
Requires-Dist: httpx>=0.28.1
Requires-Dist: litellm>=1.81.10
Requires-Dist: mcp>=1.0.0
Requires-Dist: pydantic>=2.12.5
Requires-Dist: python-dotenv>=1.2.1
Requires-Dist: pyyaml>=6.0
Requires-Dist: rich>=13.0
Requires-Dist: uvicorn>=0.40.0
Description-Content-Type: text/markdown

# 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

```bash
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

```bash
cd frontend
pnpm install
pnpm dev
```

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

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

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

### 3. MCP 서버 등록

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

```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 예시:**

```yaml
---
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 |
