Task Researcher

Task Researcher

knowledge-storm ライブラリを使用した、詳細なリサーチ機能を統合した、AI 主導の開発向け Python タスク管理システムです。複雑なプロジェクトを分解してタスクを生成し、自動リサーチを活用して実装の詳細を把握できます。

このパッケージは、コマンドラインインターフェース（CLI）と Model Context Protocol（MCP）サーバーの両方を提供します。

主な機能

• 入力の解析：プロジェクトの仕様ファイル（functional_spec.md、technical_spec.md、plan.md、background.md）から初期タスクを生成します。
• タスクの展開：
  • AI（litellm 経由の claude、gemini など）を使用して、タスクをサブタスクに分解します。
  • STORM を活用したリサーチ（--research フラグ）：複雑なタスクについて、リサーチの質問を自動的に特定してトピックごとにまとめ、各トピックに対して knowledge-storm エンジンを実行します。さらに、集約したリサーチ結果を使って、十分な情報に基づいたサブタスクを生成します。
• タスクの更新：新しいプロンプトや要件の変更に基づいて、未完了のタスクを変更します。
• 複雑さの分析：AI を使用してタスクの複雑さを評価し、推奨事項とタスクに合わせた展開プロンプトを含むレポートを生成します（--research-hint フラグを利用できます）。
• 依存関係の管理：依存関係の問題（参照の欠落、自己依存、単純な循環）を検証し、自動的に修正します。
• ファイルの生成：各タスクとサブタスクの個別の .txt ファイルを作成します。
• スタンドアロンリサーチ（research-topic）：knowledge-storm を使用して、あらゆるトピックについて詳細なリサーチレポートを生成します。

要件

• Python 3.10+
• .env ファイルに設定された、少なくとも 1 つの対応 LLM プロバイダー（例：Anthropic、Google Gemini、OpenAI）の API キー（タスク生成、複雑さの分析などで使用します）。
• knowledge-storm ライブラリ（pip install knowledge-storm）。
• .env に設定された、knowledge-storm が対応する検索エンジン（例：Bing Search、You.com、Tavily）の API キー（expand の --research と research-topic コマンドで必須です）。
• （任意）MCP サーバーとして実行する場合は mcp ライブラリ（pip install mcp）。

インストール

1. リポジトリをクローンします：

   git clone <repository-url>
   cd task-researcher
   

2. 依存関係をインストールします（Poetry の使用を推奨）：

   pip install poetry
   poetry install
   

3. 環境を設定します：
   • .env.example を .env にコピーします。
   • 主に使用する LLM の API キー（例：ANTHROPIC_API_KEY）を設定します。
   • 主なタスク用の LLM_MODEL を設定します（例："claude-3-5-sonnet-20240620"）。
   • STORM_RETRIEVER（例："bing"）と、対応する API キー（BING_SEARCH_API_KEY）を設定します。
   • （任意）STORM リサーチで別のモデル（例：より高速または低コストのモデル）を使用するには、BIG_STORM_MODEL と SMALL_STORM_MODEL を設定します。
   • （任意）MAX_TOKENS、TEMPERATURE、ファイルパスなど、その他の設定を調整します。

コマンドラインインターフェース（CLI）の使用方法

（Poetry のスクリプト経由でインストールした場合は）task-researcher コマンド、または python -m task_researcher を使用します。

# Show help
task-researcher --help

# Generate initial tasks from spec files in ./scripts/
task-researcher parse-inputs --num-tasks 20

# Analyze complexity (using primary LLM's knowledge)
task-researcher analyze-complexity --research-hint

# View the complexity report
task-researcher complexity-report

# --- Expanding Tasks ---

# Expand task 5 normally (using primary LLM)
task-researcher expand --id 5 --num 4

# Expand task 7 using the STORM research workflow (will ask for confirmation)
# Generates questions -> groups topics -> runs STORM -> generates subtasks w/ research)
# Will show research plan & token estimate, ask for confirmation before running STORM
task-researcher expand --id 7 --research

# Expand all eligible tasks using STORM research workflow
task-researcher expand --all --research

# Expand task 9, forcing overwrite, using STORM, with extra user context
task-researcher expand --id 9 --research --force --prompt "Ensure compatibility with React 19 features."

# --- Other Commands ---

# Update tasks from ID 4 onwards due to a change
task-researcher update --from 4 --prompt "Refactor authentication to use JWT instead of session cookies."

# Validate dependencies
task-researcher validate-deps

# Fix dependencies automatically
task-researcher fix-deps

# Generate individual .txt task files
task-researcher generate

# Generate a standalone research report on a topic using STORM
task-researcher research-topic "Comparison of Vector Databases for RAG" -o "reports/vector_db_comparison.md" --retriever tavily # Requires TAVILY_API_KEY

MCP サーバー

このパッケージは MCP サーバーとしても実行でき、その機能をツールやリソースとして公開し、Claude Desktop、Cursor、またはカスタムアプリケーションなどの MCP クライアントから利用できます。

サーバーの実行：

poetry run task-researcher serve-mcp
# OR
poetry run python -m task_researcher.mcp.server

これにより、デフォルトの stdio トランスポート を使用してサーバーが起動します。

クライアントからの接続（例：Claude Desktop）：

1. Claude Desktop の設定を開き、［Developer］→［Edit Config］を選択します。
2. claude_desktop_config.json の mcpServers に項目を追加します：

{
  "mcpServers": {
    "task-researcher": {
      // Adjust command based on your environment (Poetry vs. global python)
      // Option 1: Using Poetry
      "command": "poetry", // Or the full path to your poetry executable
      "args": [
        "run",
        "task-researcher", // The script name from pyproject.toml
        "serve-mcp"
      ],
      // Make sure poetry run executes in the correct project directory
      "options": {
          "cwd": "/absolute/path/to/your/task-researcher/project"
      }
      // Option 2: Assuming task-researcher is installed globally or in PATH
      // "command": "task-researcher",
      // "args": ["serve-mcp"]
      // Option 3: Direct Python execution
      // "command": "python", // Or python3 or full path
      // "args": [
      //     "-m",
      //     "task_researcher.mcp.server",
      //      // Specify the working directory if needed relative paths are used in config
      //      // or ensure .env is found relative to where python is run
      // ],
      // "options": { // Ensure correct working directory if needed
      //     "cwd": "/absolute/path/to/your/task-researcher/project"
      // }
    }
    // Add other servers here...
  }
}

3. /absolute/path/to/your/task-researcher/project を、クローンしたリポジトリの実際のパスに置き換えます。
4. Claude Desktop を再起動します。

公開されている MCP ツール：

• parse_inputs：設定された仕様ファイルから初期タスクを生成します。
• update_tasks：プロンプトに基づいて、指定した ID 以降のタスクを更新します。
• generate_task_files：個別の phase_XX_task_YYY.txt ファイルを作成します。
• expand_task：単一のタスクをサブタスクに展開します（STORM 用の research=True に対応）。
• expand_all_tasks：展開可能な保留中のタスクをすべて展開します（research=True に対応）。
• analyze_complexity：タスクの複雑さを分析し、レポートを保存します。
• validate_dependencies：依存関係に問題がないか確認します。
• fix_dependencies：依存関係の問題を自動的に修正しようとします。
• research_topic：STORM を実行して、トピックに関する調査レポートを生成します。

（注：MCP 経由の expand_* --research は確認を省略します。）

公開されている MCP リソース：

• tasks://current：メインの tasks.json ファイルの内容です。
• report://complexity：task-complexity-report.json ファイルの内容です。
• research://{topic_name}：指定したトピックの、生成済み STORM レポートの内容です。
• taskfile://{task_id_str}：特定の phase_XX_task_YYY.txt ファイルの内容です。

（ツール／リソースの正確な定義とパラメーターについては、mcp/server.py を参照してください。）

--research と --research-hint の違い

• expand --research：STORM ベースの完全なワークフローを実行します。AI が質問を生成 → AI が質問をグループ化 → knowledge-storm がウェブ検索を実行してレポートを統合 → AI が統合されたレポートをコンテキストとしてサブタスクを生成します。knowledge-storm と、設定済みのリトリーバー API キーが必要です。
• analyze-complexity --research-hint：複雑さの分析を行うプライマリ LLM へのプロンプトを変更し、調査アシスタントのように内部ナレッジベースをより深く活用するよう促します。knowledge-storm は使用せず、リアルタイムのウェブ検索も実行しません。
• update --research-hint：analyze-complexity と同様に、更新プロンプトの処理時にプライマリ LLM が内部知識を活用するよう促します。

設定（.env）

.env.example を参照してください。主な設定は次のとおりです。

• LLM_MODEL：タスク、分析、サブタスク生成（STORM 以外）に使用するプライマリモデルです。
• ANTHROPIC_API_KEY、GOOGLE_API_KEY など：プライマリ LLM の認証情報です。
• STORM_RETRIEVER：STORM の検索エンジンです（bing、you、tavily など）。
• BING_SEARCH_API_KEY、YDC_API_KEY、TAVILY_API_KEY など：選択した STORM リトリーバーのキーです。
• BIG_STORM_MODEL：（任意）STORM の内部処理に使用する大型モデルです。
• SMALL_STORM_MODEL：（任意）STORM の内部処理に使用する小型モデルです。
• STORM_SEARCH_TOP_K、STORM_MAX_TOKENS_*：STORM の調査の深さを制御します。
• ファイルパス（TASKS_FILE_PATH など）。

タスクの構造（tasks/tasks.json）

構造は、task_master_py/models.py で定義されている Pydantic モデルに従っており、Task、Subtask、TasksData が含まれます。

{
  "meta": {
    "projectName": "Task Master Project",
    "projectVersion": "0.1.2",
    "sourceFiles": ["scripts/plan.md", "..."],
    "generatedAt": "...",
    "totalTasks": 15
  },
  "tasks": [
    {
      "id": 1,
      "title": "Setup Project Environment",
      "phase": 1,
      "description": "Initialize project structure, install dependencies, configure linters.",
      "details": "...",
      "status": "pending",
      "dependencies": [],
      "priority": "high",
      "testStrategy": "Verify environment setup by running basic commands.",
      "subtasks": []
    },
    {
      "id": 2,
      "title": "Implement Core Data Models",
      "phase": 1,
      "description": "Define Pydantic models for tasks and reports.",
      "details": "...",
      "status": "pending",
      "dependencies": [1], // Depends on task 1
      "priority": "high",
      "testStrategy": "Unit tests for model validation.",
      "subtasks": [
        {
            "id": 1, // Subtask ID is relative to parent
            "title": "Define Task Model",
            "description": "...",
            "details": "...",
            "status": "pending",
            "dependencies": [], // Dependencies relative to sibling subtasks (ints)
            "acceptanceCriteria": "Pydantic model passes validation...",
        },
        {
            "id": 2,
            "title": "Define Report Model",
            "description": "...",
            "details": "...",
            "status": "pending",
            "dependencies": [1], // Depends on subtask 1
            "acceptanceCriteria": "Pydantic model passes validation...",
        }
      ]
    },
    // ... more tasks
  ]
}