Nexus AI Tools

AIアシスタントのための包括的なModel Context Protocolツールキット

License: MIT Node Version TypeScript MCP

あらゆるAIアシスタントを、現実世界のタスクを実行可能な自律型エージェントに変身させます。

ドキュメント • はじめに • ロードマップ • アーキテクチャ

🎯 概要

Nexus-MCPは、TypeScript/Node.jsで構築された強力なModel Context Protocol (MCP) サーバーであり、AIモデルに以下のための汎用ツールを提供します：

📁 ファイルシステム操作 (18ツール) - ファイルの読み取り、書き込み、検索、監視
🌐 HTTP/Webリクエスト (16ツール) - データの取得、Webサイトのスクレイピング、API呼び出し
🔄 Gitワークフロー (15ツール) - クローン、コミット、ブランチ、リポジトリ管理
システムコマンド (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 - Webコンテンツの取得と解析
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バリデーション
✅ エラーハンドリング: 構造化された実用的なエラーメッセージ
✅ パフォーマンス: 非同期操作、キャッシュ、ストリーミング
✅ セキュリティ: 入力バリデーション、サニタイズ、監査ログ
✅ 可観測性: 構造化ログ、メトリクス、トレーシング
✅ テスト容易性: 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 (Model Context Protocol) サーバーです。

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ファイルを参照してください。

🙏 謝辞

Model Context Protocol
Anthropic Claude
MCP SDK TypeScript
App Migración SOUL - 設定パターンとコンテキストロギングの着想元

📞 サポート

Built with ❤️ by the Nexus Team

Nexus-MCP