qwencode-mcp-server: Instructions file for Claude Code

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

プロジェクト概要

QwenCode MCP Server は、Model Context Protocol (MCP) を使用して AI アシスタントが Qwen AI モデルと対話できるようにするサーバーです。

現在、このプロジェクトは単一目的の Qwen ツールから、汎用の AI プロバイダーフレームワークへの移行が進行中です（docs/PLAN.md および docs/ROADMAP.md を参照）。

開発コマンド

# ビルド
npm run build

# 開発（ビルドして実行）
npm run dev

# 実行（ビルド済み）
npm start

# テスト実行
npm test

# リント（TypeScript 型チェックのみ）
npm run lint

# 単一のテストファイルを実行
node --test test/tools.test.js
node --test test/registry.test.js

アーキテクチャ

メタデータ駆動設計

プロジェクトの核となる概念は、CLI ツールの機能をメタデータとして記述し、そこから MCP ツールを動的に生成することです。

CliToolMetadata → DynamicToolFactory → MCP Tool

コアコンポーネント

コンポーネント	役割	ファイル
AIProvider	全プロバイダーの共通インターフェース	src/providers/base-cli.provider.ts
BaseCliProvider	CLI ベースプロバイダーの抽象基底クラス	src/providers/base-cli.provider.ts
QwenProvider	Qwen の具象実装	src/providers/qwen.provider.ts
CliToolMetadata	CLI ツールの機能を記述する型	src/types/cli-metadata.ts
DynamicToolFactory	メタデータから MCP ツールを生成	src/tools/dynamic-tool-factory.ts
toolRegistry	登録されたツールの一元管理	src/tools/registry.ts

ツール登録の流れ

1. src/tools/index.ts でプロバイダーをインスタンス化
2. registerProvider(new QwenProvider()) で登録
3. DynamicToolFactory がメタデータから Zod スキーマと実行ロジックを生成
4. MCP サーバーがツール定義をクライアントに公開

進行中のリファクタリング（Phase 1-3）

• Phase 1: 基盤となる型とクラス構造の確立（完了）
• Phase 2: 既存の Qwen ロジックを新しい構造に移行（完了）
• Phase 3: メインアプリケーションフローとの統合（完了）

将来のロードマップ（Phase 4+）

• HelpParser: CLI --help 出力からメタデータを自動生成
• 汎用プロバイダー: OpenAI、Ollama、Anthropic などのサポート
• 設定ファイル駆動: ユーザーがコードを変更せずにツールを追加可能に

ファイル構成

src/
├── index.ts              # MCP サーバーのエントリーポイント
├── constants.ts          # 定数・型定義
├── types/
│   └── cli-metadata.ts   # CliToolMetadata、CliOption などの型
├── providers/
│   ├── base-cli.provider.ts  # AIProvider インターフェース、BaseCliProvider
│   └── qwen.provider.ts      # QwenProvider の実装
├── tools/
│   ├── index.ts              # ツール登録のエントリーポイント
│   ├── registry.ts           # toolRegistry、registerProvider
│   ├── dynamic-tool-factory.ts  # メタデータからツールを生成
│   ├── simple-tools.ts       # Ping、Help などの静的ツール
│   └── ask-qwen.tool.ts      # （非推奨）QwenProvider に置換済み
└── utils/
    ├── commandExecutor.ts    # CLI コマンド実行（10分タイムアウト）
    ├── logger.ts             # ログ出力（NO_COLOR 対応）
    └── progressManager.ts    # MCP 進行状況通知