nexus-agent-platform 0.3.0

AI agent platform with MCP tool integration

Nexus Agent Platform

MCP(Model Context Protocol) + Agent Skills 기반 범용 AI Agent 플랫폼.

하나의 명령으로 설치하고, 하나의 명령으로 프론트엔드+백엔드를 실행합니다.

pip install nexus-agent-platform   # 설치
nexus-agent init                   # 초기 설정
nexus-agent start                  # 실행 → http://localhost:8000

---

설치

사전 준비: uv 설치

uv는 Python 패키지 관리 도구입니다. 먼저 uv를 설치합니다.

macOS / Linux:

curl -LsSf https://astral.sh/uv/install.sh | sh

Windows (PowerShell):

powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"

설치 후 터미널을 재시작하거나 source ~/.bashrc (macOS/Linux) 또는 새 PowerShell 창을 엽니다.

방법 1: uv (권장)

uv tool install nexus-agent-platform

방법 2: pipx

pipx install nexus-agent-platform

방법 3: pip

pip install nexus-agent-platform

요구사항

• Python 3.13 이상 (uv가 자동으로 설치합니다)
• 지원 프로바이더 중 최소 1개의 API Key (아래 API 키 설정 참고)

플랫폼 지원

OS	상태	데이터 디렉토리
macOS	테스트 완료	~/.nexus-agent/
Linux	지원	~/.nexus-agent/
Windows	지원	C:\Users\<사용자>\.nexus-agent\

---

빠른 시작

1. 초기 설정

nexus-agent init

~/.nexus-agent/ 디렉토리에 설정 파일이 생성됩니다:

~/.nexus-agent/
├── .env              # API 키 설정
├── settings.json     # LLM 설정 (모델, 온도, 시스템 프롬프트)
├── mcp.json          # MCP 서버 설정
├── skills.json       # 스킬 활성화 상태
├── pages.json        # 페이지 메타데이터
├── skills/           # Agent Skills 저장 디렉토리
└── pages/            # 업로드된 HTML 저장 디렉토리

2. API 키 설정

~/.nexus-agent/.env 파일에 사용할 프로바이더의 API 키를 설정합니다. 사용할 프로바이더만 설정하면 됩니다 (전부 설정할 필요 없음).

# Google Gemini — https://aistudio.google.com/apikey
GOOGLE_API_KEY=AIzaSy...

# OpenAI — https://platform.openai.com/api-keys
OPENAI_API_KEY=sk-proj-...

# Anthropic (Claude) — https://console.anthropic.com/settings/keys
ANTHROPIC_API_KEY=sk-ant-...

# xAI (Grok) — https://console.x.ai
XAI_API_KEY=xai-...

macOS / Linux:

# 예시: Google Gemini만 사용하는 경우
echo "GOOGLE_API_KEY=your-api-key-here" > ~/.nexus-agent/.env

# 여러 프로바이더를 사용하는 경우
cat > ~/.nexus-agent/.env << 'EOF'
GOOGLE_API_KEY=AIzaSy...
OPENAI_API_KEY=sk-proj-...
ANTHROPIC_API_KEY=sk-ant-...
XAI_API_KEY=xai-...
EOF

Windows (PowerShell):

# 예시: Google Gemini만 사용하는 경우
Set-Content "$env:USERPROFILE\.nexus-agent\.env" "GOOGLE_API_KEY=your-api-key-here"

Settings 페이지(/settings)에서 모델을 선택하면, 해당 프로바이더의 API 키가 자동으로 사용됩니다.

3. 서버 시작

nexus-agent start

브라우저에서 http://localhost:8000 을 열면 UI가 표시됩니다.

$ nexus-agent start
Nexus Agent v0.1.1 starting on http://0.0.0.0:8000
INFO:     Loading settings...
INFO:     Loading MCP config and connecting servers...
INFO:     Loading skills...
INFO:     Loading pages...
INFO:     Uvicorn running on http://0.0.0.0:8000

4. 옵션

nexus-agent start --port 9000      # 포트 변경
nexus-agent start --host 127.0.0.1 # 로컬만 허용
nexus-agent start --dev            # 개발 모드 (CORS 허용, 자동 리로드)

---

CLI 명령어

명령어	설명
nexus-agent init	~/.nexus-agent/ 초기 설정 파일 생성
nexus-agent start	서버 시작 (UI + API 단일 포트)
nexus-agent start --dev	개발 모드 (CORS 허용, 자동 리로드)
nexus-agent start --port 9000	커스텀 포트로 시작
nexus-agent config	현재 설정 경로 및 상태 표시
nexus-agent update	최신 버전으로 업데이트
nexus-agent --version	버전 확인
nexus-agent --help	도움말 표시

---

주요 기능

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)

• 테마 커스터마이징: 액센트 컬러, 다크/라이트 모드, 배경 톤
• 채팅 배경 이미지: 프리셋 선택, 커스텀 업로드
• LLM 설정: 모델 선택, API 키, 온도, 최대 토큰, 시스템 프롬프트
• 사용자 프로필: 이름, 아바타

---

아키텍처

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

기술 스택

계층	기술
Frontend	Next.js 16, React 19, TypeScript, Tailwind CSS, shadcn/ui
Backend	Python 3.13, FastAPI, Pydantic
LLM	Gemini, OpenAI, Claude, Grok (LiteLLM 추상화)
Tool System	MCP (Model Context Protocol) + Agent Skills
CLI	Click, Rich
패키지	PyPI (nexus-agent-platform), Hatchling

프로젝트 구조

nexus-agent/
├── pyproject.toml              # 패키지 설정 및 의존성
├── nexus_agent/                # Python 패키지
│   ├── cli.py                  # CLI 엔트리포인트 (nexus-agent 명령)
│   ├── server.py               # FastAPI 앱 + 정적 파일 서빙
│   ├── config.py               # ~/.nexus-agent/ 데이터 디렉토리 관리
│   ├── 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 설정 관리
│   ├── api/endpoints/          # API 라우터
│   ├── models/                 # Pydantic 데이터 모델
│   └── static/                 # 빌드된 프론트엔드 (wheel에 포함)
├── frontend/                   # 프론트엔드 소스 (개발용)
│   ├── src/
│   └── package.json
└── scripts/
    └── build.sh                # 통합 빌드 스크립트

---

MCP 서버 등록

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

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

전송 방식

transport	필수 필드	예시
stdio	command, args	"command": "npx", "args": ["-y", "some-mcp-server"]
sse	url	"url": "http://localhost:3001/sse"
streamable-http	url	"url": "http://localhost:3001/mcp"

---

Agent Skill 등록

프론트엔드 Agent Skills 대시보드(/skills)에서 등록하거나, ~/.nexus-agent/skills/ 디렉토리에 스킬 폴더를 생성합니다.

~/.nexus-agent/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/ 에 있는 문서를 참조할 수 있습니다

---

환경 변수

~/.nexus-agent/.env

변수	필수	설명	발급
GOOGLE_API_KEY	선택	Google Gemini API 키	AI Studio
OPENAI_API_KEY	선택	OpenAI API 키	Platform
ANTHROPIC_API_KEY	선택	Anthropic Claude API 키	Console
XAI_API_KEY	선택	xAI Grok API 키	Console

사용할 프로바이더의 키만 설정하면 됩니다. Settings 페이지에서 모델을 선택하면 해당 프로바이더의 키가 자동으로 사용됩니다.

지원 모델 (프로바이더별)

Settings 페이지(/settings)에서 모델을 선택하거나, settings.json의 model 필드에 직접 입력합니다.

프로바이더	모델 예시	환경변수
Google Gemini	gemini/gemini-3-flash-preview, gemini/gemini-2.5-pro	GOOGLE_API_KEY
OpenAI	openai/gpt-5, openai/gpt-4.1, openai/o3	OPENAI_API_KEY
Anthropic	anthropic/claude-opus-4-6, anthropic/claude-sonnet-4-5-20250929	ANTHROPIC_API_KEY
xAI	xai/grok-4-1-fast-reasoning, xai/grok-3	XAI_API_KEY
Self-hosted	openai/<모델명> + API Base URL 설정	(아래 참고)

LLM 설정 (~/.nexus-agent/settings.json)

웹 UI의 Settings 페이지에서 변경하거나 직접 편집합니다:

{
  "llm": {
    "model": "gemini/gemini-2.5-flash",
    "temperature": 0.7,
    "max_tokens": 4096,
    "system_prompt": ""
  }
}

사내 vLLM / Self-hosted 사용

사내 네트워크에 vLLM으로 호스팅된 OpenAI 호환 API 서버에 연결할 수 있습니다.

1. .env 설정:

# OpenAI-compatible H200 MIG API 120B LLM Configuration (for vLLM)
OPENAI_API_BASE=http://192.168.1.120:11436/v1

# API Key (dummy for local hosted vLLM - required by LiteLLM)
OPENAI_API_KEY=dummy

2. Settings 페이지 또는 settings.json에서 모델 설정:

설정 항목	값
Model	hosted_vllm/openai/gpt-oss-120b
API Base URL	http://192.168.1.120:11436/v1

{
  "llm": {
    "model": "hosted_vllm/openai/gpt-oss-120b",
    "api_base": "http://192.168.1.120:11436/v1",
    "api_key": "dummy",
    "temperature": 0.7,
    "max_tokens": 4096
  }
}

LiteLLM 추상화 계층을 사용하므로 OpenAI 호환 API를 제공하는 모든 서버(vLLM, Ollama, TGI 등)에 연결 가능합니다.

---

개발 환경

프론트엔드와 백엔드를 분리하여 개발할 수 있습니다.

백엔드 개발

git clone https://github.com/EJCHO-salary/track_platform.git
cd track_platform
uv sync
uv run nexus-agent init
uv run nexus-agent start --dev    # 개발 모드 (리로드 + CORS 허용)

프론트엔드 개발

cd frontend
pnpm install
pnpm dev    # http://localhost:3000 (백엔드는 별도로 실행 필요)

프론트엔드 개발 시 백엔드 주소가 다르면 frontend/.env.local을 생성합니다:

NEXT_PUBLIC_API_URL=http://localhost:8000

프론트엔드 포함 빌드 (wheel)

./scripts/build.sh
# 1. frontend/ 빌드 (static export)
# 2. nexus_agent/static/ 에 복사
# 3. uv build → dist/ 에 wheel 생성

---

포트

서비스	URL	용도
nexus-agent start	http://localhost:8000	프로덕션 (UI + API 통합)
nexus-agent start --dev	http://localhost:8000	개발 (API only, CORS 허용)
pnpm dev	http://localhost:3000	프론트엔드 개발 서버
Swagger Docs	http://localhost:8000/docs	API 문서

---

버전 확인

nexus-agent --version

업데이트 (업그레이드)

# CLI 명령으로 업데이트
nexus-agent update

# 또는 설치 도구로 직접 업그레이드
uv tool upgrade nexus-agent-platform    # uv 사용 시
pipx upgrade nexus-agent-platform       # pipx 사용 시
pip install --upgrade nexus-agent-platform  # pip 사용 시

업데이트 후 서버를 재시작하면 적용됩니다:

nexus-agent start

~/.nexus-agent/ 디렉토리의 설정 파일은 업데이트 시 유지됩니다. nexus-agent init을 다시 실행할 필요는 없습니다.

---

CI/CD (자동 배포)

GitHub에 태그를 push하면 자동으로 PyPI에 배포됩니다.

사전 설정 (1회)

1. PyPI → 프로젝트 → Settings → Publishing → Add a new publisher
2. 아래 정보를 입력:
   • Owner: EJCHO-salary
   • Repository: track_platform
   • Workflow name: publish.yml
   • Environment: (비워둠)

배포 방법

# 1. pyproject.toml과 __init__.py의 버전을 올린다
# 2. 커밋하고 태그를 생성한다
git tag v0.1.2
git push origin main --tags

# GitHub Actions가 자동으로:
# - 프론트엔드 빌드
# - 정적 파일 복사
# - wheel 빌드
# - PyPI 배포

수동 배포

./scripts/build.sh
uv publish -t pypi-YOUR_TOKEN

---

라이선스

MIT