Nexus AI 도구

AI 어시스턴트를 위한 포괄적인 모델 컨텍스트 프로토콜(MCP) 툴킷

License: MIT Node Version TypeScript MCP

모든 AI 어시스턴트를 실제 작업을 수행할 수 있는 자율 에이전트로 변환하세요.

문서 • 시작하기 • 로드맵 • 아키텍처

🎯 개요

Nexus-MCP는 TypeScript/Node.js로 구축된 강력한 모델 컨텍스트 프로토콜(MCP) 서버로, AI 모델에 다음과 같은 범용 도구를 제공합니다:

📁 파일 시스템 작업 (18개 도구) - 파일 읽기, 쓰기, 검색 및 모니터링
🌐 HTTP/웹 요청 (16개 도구) - 데이터 가져오기, 웹사이트 스크래핑, API 호출
🔄 Git 워크플로우 (15개 도구) - 복제(Clone), 커밋, 브랜치 및 저장소 관리
시스템 명령 (8개 도구) - 셸 명령 실행 및 프로세스 관리
🔧 유틸리티 (8개 도구, 코드 준비 완료) - JSON/YAML 파싱, 압축, 암호화 등

현재 상태: 49개 도구 프로덕션 준비 완료, 8개 유틸리티 도구 코드 구현 완료(구성 통합 대기 중)

🚀 빠른 시작

설치

npm install -g nexus-ai-tools

구성

# Copy example environment file
cp .env.example .env

# Edit with your settings
nano .env

실행

# Build the project
npm run build

# Run the MCP server (production)
npm start
# or
npm run start:mcp

# Run with CLI
npm run mcp

# Run in development mode
npm run dev

Claude Code와 통합

Claude Desktop 구성에 추가:

{
  "mcpServers": {
    "nexus-mcp": {
      "command": "node",
      "args": ["/path/to/nexus-mcp/dist/index.js"]
    }
  }
}

환경 변수 치환 사용

.env 파일 생성:

NEXUS_LOG_LEVEL=debug
DB_PASSWORD=secret123
ANTHROPIC_API_KEY=sk-ant-...

config.yaml에서 사용:

server:
  log_level: "${NEXUS_LOG_LEVEL:-info}"
database:
  postgresql:
    password: "${DB_PASSWORD}"
ai:
  anthropic:
    api_key: "${ANTHROPIC_API_KEY}"

시작 전 필수 변수 검증:

import { validateEnvironment, loadConfig } from './config.js';

validateEnvironment(['ANTHROPIC_API_KEY', 'DB_PASSWORD']);
const config = loadConfig();

컨텍스트 로거 사용

import { ContextualLogger } from './logger.js';
import path from 'path';

const workDir = path.join(process.cwd(), 'logs');
const logger = ContextualLogger.create(workDir, 'workflow-001');

logger.info('workflow.started', { step: 1 });
logger.info('processing.data', { items: 100 });
logger.info('workflow.completed', { success: true });

logger.close();

자세한 내용은 구성 개선 가이드를 참조하세요.

📦 기능

파일 시스템 도구

nexus_read_file - 인코딩 지원을 통한 파일 읽기
nexus_write_file - 파일 쓰기/생성
nexus_list_directory - 디렉토리 내용 나열
nexus_search_files - 패턴별 파일 검색
nexus_search_content - 파일 내 콘텐츠 검색
nexus_watch_directory - 디렉토리 변경 모니터링

HTTP 도구

nexus_http_get - HTTP GET 요청
nexus_http_post - HTTP POST 요청
nexus_fetch_url - 웹 콘텐츠 가져오기 및 파싱
nexus_parse_html - Cheerio를 사용한 HTML 파싱
nexus_call_api - 일반 API 호출

Git 도구

nexus_git_clone - 저장소 복제
nexus_git_commit - 커밋 생성
nexus_git_push - 원격 저장소로 푸시
nexus_git_pr_create - 풀 리퀘스트 생성
GitHub, GitLab, Bitbucket 통합

데이터베이스 도구

nexus_db_query - SQL 쿼리 실행
nexus_db_list_tables - 데이터베이스 테이블 나열
nexus_db_describe_table - 테이블 스키마 설명
PostgreSQL, MySQL, SQLite, SQL Server, MongoDB 지원

시스템 도구

nexus_exec_command - 셸 명령 실행
nexus_system_info - 시스템 정보 가져오기
nexus_process_list - 실행 중인 프로세스 나열
nexus_service_start/stop - 서비스 관리

AI 도구

nexus_llm_chat - LLM과 채팅 (Anthropic, OpenAI)
nexus_embedding_create - 텍스트 임베딩 생성
nexus_text_summarize - 텍스트 요약
nexus_code_generate - 코드 생성

유틸리티 도구

nexus_json_parse/stringify - JSON 조작
nexus_yaml_parse/stringify - YAML 조작
nexus_zip_create/extract - ZIP 압축
nexus_encrypt/decrypt - 암호화/복호화

🏗️ 아키텍처

┌─────────────────────────────────────────┐
│         Claude / LLM Client              │
└──────────────┬──────────────────────────┘
               │ MCP Protocol (stdio)
               ▼
┌─────────────────────────────────────────┐
│           Nexus-MCP Server               │
│  ┌───────────────────────────────────┐  │
│  │      MCP Server Core             │  │
│  └───────────────────────────────────┘  │
│         ┌───────┴───────┐                │
│         │               │                │
│    ┌────▼────┐    ┌────▼────┐           │
│    │ Filesys │    │   HTTP  │           │
│    └─────────┘    └─────────┘           │
│    ┌─────────┐    ┌─────────┐           │
│    │   Git   │    │ Database│           │
│    └─────────┘    └─────────┘           │
│    ┌─────────┐    ┌─────────┐           │
│    │  System │    │    AI   │           │
│    └─────────┘    └─────────┘           │
└─────────────────────────────────────────┘

상세 아키텍처는 docs/architecture.md를 참조하세요.

🏛️ 프로덕션급 품질

Nexus-MCP는 아키텍처적 우수성을 염두에 두고 구축되었으며, 프로덕션 사용 및 커뮤니티 채택을 위해 설계되었습니다. 우리는 엄격한 원칙을 따릅니다:

✅ 타입 안전성: TypeScript 엄격 모드 + Zod 유효성 검사
✅ 오류 처리: 구조화되고 실행 가능한 오류 메시지
✅ 성능: 비동기 작업, 캐싱, 스트리밍
✅ 보안: 입력 유효성 검사, 살균(Sanitization), 감사 로그
✅ 관측 가능성: 구조화된 로깅, 메트릭, 추적
✅ 테스트 가능성: 80% 이상의 커버리지, 의존성 주입
✅ 문서화: JSDoc, 예제, 포괄적인 가이드
✅ 개발자 경험: 명확한 오류, IDE 지원, 빠른 피드백

자세한 내용은 아키텍처 원칙을 참조하세요.

⚙️ 구성 및 로깅 개선

Nexus-MCP는 프로덕션 시스템에서 영감을 받은 고급 구성 및 로깅 기능을 포함합니다:

환경 변수 치환

YAML 파일에서 ${VAR_NAME} 구문을 사용하여 환경 변수를 치환합니다:

server:
  log_level: "${NEXUS_LOG_LEVEL:-info}"  # Uses env var, defaults to "info"
database:
  postgresql:
    password: "${DB_PASSWORD}"  # Required - warns if not set

장점:

민감한 데이터(API 키, 비밀번호)를 환경 변수에 보관
환경별로 다른 구성 사용
YAML 파일을 편집하지 않고 특정 값 재정의

컨텍스트 로거

컨텍스트별로 별도의 로그 파일을 사용하는 워크플로우 전용 로깅:

import { ContextualLogger } from './logger.js';

const logger = ContextualLogger.create(workDir, 'migration-123');
logger.info('workflow.started', { step: 1 });
logger.info('extract.completed', { schemaPath: '/path/to/schema.json' });
logger.close();

장점:

엔드 투 엔드 워크플로우 추적 (마이그레이션, 작업, 배치 작업)
복잡한 다단계 작업 디버깅
워크플로우/상관관계 ID별로 로그 정리
특정 워크플로우의 이력 분석

문서: 자세한 내용은 구성 개선 가이드를 참조하세요.

📖 문서

시작하기 가이드 - 빠른 시작 및 기본 사용법
아키텍처 문서 - 시스템 아키텍처 및 설계
아키텍처 원칙 - 설계 원칙 및 모범 사례
구성 개선 - 환경 변수 치환 및 컨텍스트 로깅
API 참조 - 전체 API 문서
도구 참조 - 상세 도구 문서
로드맵 - 개발 로드맵 및 진행 상황

🛠️ 개발

# Clone repository
git clone https://github.com/your-org/Nexus-MCP.git
cd Nexus-MCP

# Install dependencies
npm install

# Run in development mode
npm run dev

# Run tests
npm test

# Build for production
npm run build

# Lint code
npm run lint

📊 프로젝트 상태

현재 버전: 1.0.0-alpha
개발 상태: 활발한 개발 중
핵심 진행률: 36% (12단계 중 9단계 완료)
구현된 도구: 57개 프로덕션 준비 완료, 8개 코드 구현 완료(구성 대기 중)
목표 도구: 50개 이상 ✅ (초과 달성)
AI 통합: Ollama + Gemini + OpenAI + Anthropic Claude ✅ (8개 도구)
향상된 CLI: 색상 및 메트릭이 포함된 대화형 AI 도구 CLI ✅
테스트 커버리지: 49개 테스트 구현 (35개 단위 + 1개 통합 + 13개 E2E)
테스트 상태: ✅ 모두 통과 (49/49)
문서화: 85% 완료 (설치, 구성, API, 예제, AI 가이드)
빌드 상태: ✅ 통과
실행 파일: ✅ 배포 준비 완료
CLI: ✅ 기능 작동

자세한 진행 상황은 ROADMAP.md를 참조하세요.

🤖 AI 도구 통합

Nexus-MCP는 4개의 주요 AI 제공업체와의 통합을 포함합니다:

Ollama (2개 도구): 로컬 LLM - 채팅 + 모델 나열
Gemini (2개 도구): Google AI - 채팅 + 모델 나열
OpenAI (2개 도구): GPT 모델 - 채팅 + 모델 나열
Anthropic (2개 도구): Claude 모델 - 채팅 + 모델 나열

AI 도구 빠른 시작

# Configure API keys
export OPENAI_API_KEY="your-key"
export GEMINI_API_KEY="your-key"
export ANTHROPIC_API_KEY="your-key"
export OLLAMA_HOST="http://localhost:11434"

# Run the interactive AI CLI
node examples/ai-interactive-cli.js

# Or run the enhanced demo
node examples/ai-enhanced-demo.js

자세한 문서는 AI 도구 가이드를 참조하세요.

🔌 MCP 통합

Nexus-MCP는 Claude Code와 같은 AI 어시스턴트가 57개의 도구를 사용할 수 있도록 하는 MCP(모델 컨텍스트 프로토콜) 서버입니다.

MCP 빠른 시작

서버 시작:

npm start

Claude Desktop을 구성하여 Nexus-MCP에 연결

자세한 설정 지침은 MCP 구성 가이드를 참조하세요.

사용 가능한 도구 카테고리

파일 시스템 (18개 도구): 파일 읽기, 쓰기, 나열, 검색
HTTP (16개 도구): 요청, 스크래핑, API
Git (15개 도구): 복제, 커밋, 브랜치, PR
시스템 (8개 도구): 명령, 프로세스, 시스템 정보
AI (8개 도구): Ollama, Gemini, OpenAI, Anthropic과 채팅
유틸리티 (8개 도구): JSON, YAML, 압축, 암호화

🤝 기여

기여를 환영합니다! PR을 제출하기 전에 기여 가이드라인을 읽어주세요.

저장소 포크
기능 브랜치 생성 (git checkout -b feature/amazing-feature)
변경 사항 커밋 (git commit -m 'Add amazing feature')
브랜치로 푸시 (git push origin feature/amazing-feature)
풀 리퀘스트 열기

📄 라이선스

이 프로젝트는 MIT 라이선스에 따라 라이선스가 부여됩니다. 자세한 내용은 LICENSE 파일을 참조하세요.

🙏 감사의 말

모델 컨텍스트 프로토콜
Anthropic Claude
MCP SDK TypeScript
App Migración SOUL - 구성 패턴 및 컨텍스트 로깅 영감

📞 지원

Nexus 팀이 ❤️를 담아 제작

Nexus-MCP