Agentic Tools MCP Server

Agentic Tools MCP サーバー

プロジェクト固有のストレージを備え、高度なタスク管理とエージェントのメモリー機能を AI アシスタントに提供する、包括的な Model Context Protocol（MCP）サーバーです。

🔗 エコシステム

この MCP サーバーは、タスクとメモリーを管理する統合エコシステムの一部です。

• 🖥️ VS Code 拡張機能 - VS Code でタスクやメモリーを直接管理できる、使いやすい GUI インターフェース
• ⚡ MCP サーバー（このリポジトリ） - 高度な AI エージェントツールと、インテリジェントなタスク管理用 API

💡 プロのヒント：両方を一緒に使えば、生産性を最大限に高められます！VS Code 拡張機能はビジュアルインターフェースを提供し、MCP サーバーは PRD の解析、タスクの推奨、調査機能などの高度な機能を備えた AI アシスタントとの連携を可能にします。

特徴

🎯 無制限の階層構造に対応した高度なタスク管理システム（v1.8.0）

• プロジェクト：作業を説明付きの個別プロジェクトに整理
• 統合タスクモデル：無制限の深さのネストに対応する単一のタスクインターフェース
• 無制限の階層構造：タスク → サブタスク → サブサブタスク → 無限の深さでネスト
• すべての階層で豊富な機能：すべてのタスクで優先度、複雑さ、依存関係、タグ、時間の追跡が可能
• 親子関係：parentId フィールドによる柔軟な階層構成
• 階層レベルの追跡：階層レベルを自動計算し、視覚的に表示
• ツリー表示：無制限の深さに対応した包括的な階層ツリー表示
• インテリジェントな依存関係：階層全体にわたる検証を備えたタスク依存関係の管理
• 優先度と複雑さ：すべての階層で 1～10 の尺度による優先順位付けと複雑さの見積もり
• 強化されたステータス追跡：保留中、進行中、ブロック中、完了のステータスワークフロー
• タグベースの整理：柔軟な分類とフィルタリング
• 時間の追跡：プロジェクト計画向けの見積もり時間と実績時間
• 自動移行：従来の 3 階層モデルから無制限の深さのモデルへシームレスにアップグレード
• 進捗の追跡：すべての階層レベルで完了状況を監視
• プロジェクト固有のストレージ：各作業ディレクトリに分離されたタスクデータを保存
• Git で追跡可能：タスクデータをコードと一緒にコミット可能

🧠 エージェントメモリーシステム

• 永続メモリー：タイトルと詳細な内容を付けてエージェントのメモリーを保存・取得
• インテリジェント検索：タイトル、内容、カテゴリを対象に、関連度スコアリングを備えた複数フィールドのテキスト検索
• スマートランキング：タイトルの一致（60％）、内容の一致（30％）、カテゴリボーナス（20％）を優先する高度なスコアリングアルゴリズム
• 豊富なメタデータ：コンテキストを強化する柔軟なメタデータシステム
• JSON ストレージ：カテゴリごとに整理され、メモリータイトルをファイル名とする個別の JSON ファイル
• プロジェクト固有：作業ディレクトリごとに分離されたメモリーストレージ

🔧 利用可能な MCP ツール

プロジェクト管理

• list_projects - 作業ディレクトリ内のすべてのプロジェクトを表示
• create_project - 作業ディレクトリに新しいプロジェクトを作成
• get_project - プロジェクトの詳細情報を取得
• update_project - プロジェクト名や説明を編集
• delete_project - プロジェクトと関連するすべてのデータを削除

タスク管理（無制限の階層 v1.8.0）

• list_tasks - 無制限の深さを視覚化した階層ツリー形式でタスクを表示します
• create_task - parentId を指定して任意の階層レベルにタスクを作成します（無制限のネストに対応）
• get_task - 階層関係を含むタスクの詳細情報を取得します
• update_task - parentId を指定してタスクやメタデータを編集したり、階層レベル間で移動したりします
• delete_task - タスクとすべての子タスクを再帰的に削除します
• move_task - 階層構造内でタスクを移動する専用ツールです
• migrate_subtasks - レガシーのサブタスクを統合モデルに変換する自動移行ツールです

高度なタスク管理（AI エージェントツール）

• parse_prd - 製品要件ドキュメントを解析し、構造化されたタスクを自動生成します
• get_next_task_recommendation - 依存関係、優先度、複雑さに基づいて、インテリジェントなタスクの推奨を取得します
• analyze_task_complexity - タスクの複雑さを分析し、複雑すぎるタスクの分割を提案します
• infer_task_progress - コードベースを分析し、実装の証拠からタスクの完了状況を推定します
• research_task - AI エージェントによる、メモリ統合機能を備えた包括的なウェブ調査を支援します
• generate_research_queries - タスク調査向けに、インテリジェントで的を絞ったウェブ検索クエリを生成します

レガシーのサブタスク管理（後方互換性）

• list_subtasks - 子タスクを表示します（レガシー互換用。現在は統合された Task モデルを使用します）
• create_subtask - 子タスクを作成します（レガシー互換用。parentId を持つタスクを作成します）
• get_subtask - タスク情報を取得します（既存のサブタスクとのレガシー互換用）
• update_subtask - 子タスクを編集します（レガシー互換用。統合された Task 操作を使用します）
• delete_subtask - 子タスクを削除します（レガシー互換用。タスクを再帰的に削除します）

エージェントメモリ管理

• create_memory - タイトルと詳細な内容を指定して新しいメモリを保存します
• search_memories - 関連度スコアリングを備えたインテリジェントな複数フィールド検索でメモリを検索します
• get_memory - メモリの詳細情報を取得します
• list_memories - 任意のフィルタリングを指定してメモリを一覧表示します
• update_memory - メモリのタイトル、内容、メタデータ、分類を編集します
• delete_memory - メモリを削除します（確認が必要です）

重要：すべてのツールでは、データの保存先を指定する workingDirectory パラメーターが必要です。これにより、プロジェクトごとにタスクとメモリを管理できます。

インストール

クイックスタート

npx -y @pimzino/agentic-tools-mcp

グローバルインストール

npm install -g @pimzino/agentic-tools-mcp

使用方法

ストレージモード

MCP サーバーは、2 つのストレージモードに対応しています。

📁 プロジェクト固有モード（デフォルト）

各プロジェクトの作業ディレクトリ内にある .agentic-tools-mcp/ サブディレクトリにデータを保存します。

npx -y @pimzino/agentic-tools-mcp

🌐 グローバルディレクトリモード

--claude フラグを使用すると、すべてのデータが標準化されたグローバルディレクトリに保存されます。

• Windows: C:\Users\{username}\.agentic-tools-mcp\
• macOS/Linux: ~/.agentic-tools-mcp/

npx -y @pimzino/agentic-tools-mcp --claude

--claude フラグの使用場面：

• Claude Desktop クライアントでの使用時（プロジェクト固有ではない使い方）
• すべてのタスクとメモリを単一のグローバルワークスペースで管理したい場合
• 複数のプロジェクトを横断して作業する AI アシスタントの場合

注：--claude フラグを使用すると、すべてのツールで workingDirectory パラメーターが無視され、代わりにグローバルディレクトリが使用されます。

Claude Desktop での使用

プロジェクト固有モード（デフォルト）

{
  "mcpServers": {
    "agentic-tools": {
      "command": "npx",
      "args": ["-y", "@pimzino/agentic-tools-mcp"]
    }
  }
}

グローバルディレクトリモード（Claude Desktop に推奨）

{
  "mcpServers": {
    "agentic-tools": {
      "command": "npx",
      "args": ["-y", "@pimzino/agentic-tools-mcp", "--claude"]
    }
  }
}

注：このサーバーには、タスク管理機能とエージェントメモリ機能の両方が含まれるようになりました。

AugmentCode での使用

プロジェクト固有モード（デフォルト）

1. Augment Settings Panel（歯車アイコン）を開きます
2. MCP サーバーを追加します：
   • 名前：agentic-tools
   • コマンド：npx -y @pimzino/agentic-tools-mcp
3. VS Code を再起動します

グローバルディレクトリモード

1. Augment Settings Panel（歯車アイコン）を開きます
2. MCP サーバーを追加します：
   • 名前：agentic-tools
   • コマンド：npx -y @pimzino/agentic-tools-mcp --claude
3. VS Code を再起動します

利用できる機能：タスク管理、エージェントのメモリ、テキストベースの検索機能。

VS Code 拡張機能を使用する場合（推奨）

最高のユーザー体験を得るには、Agentic Tools MCP Companion VS Code 拡張機能をインストールしてください。

1. Companion 拡張機能のリポジトリをクローンします
2. VS Code で開き、F5 を押して開発モードで実行します
3. すべてのタスクとメモリ管理に使える、使いやすい GUI インターフェースをお楽しみください

両方を組み合わせて使うメリット：

• 🎯 視覚的なタスク管理：優先度、複雑さ、ステータス、タグ、時間追跡に対応したリッチなフォーム
• 🎨 強化された UI：ステータスの絵文字、優先度バッジ、視覚的なインジケーター
• 🔄 リアルタイム同期：VS Code での変更が AI アシスタントですぐに利用可能
• 📁 プロジェクトとの連携：ワークスペースにシームレスに統合
• 🤖 AI との協働：人間が計画し、AI が実行することで生産性を最適化

その他の MCP クライアントを使用する場合

サーバーは STDIO トランスポートを使用し、MCP 互換のあらゆるクライアントと統合できます。

プロジェクト固有モード

npx -y @pimzino/agentic-tools-mcp

グローバルディレクトリモード

npx -y @pimzino/agentic-tools-mcp --claude

データモデル

プロジェクト

{
  id: string;           // Unique identifier
  name: string;         // Project name
  description: string;  // Project overview
  createdAt: string;    // ISO timestamp
  updatedAt: string;    // ISO timestamp
}

タスク（統合モデル v1.8.0 — 階層は無制限）

{
  id: string;                    // Unique identifier
  name: string;                  // Task name
  details: string;               // Enhanced description
  projectId: string;             // Parent project reference
  completed: boolean;            // Completion status
  createdAt: string;             // ISO timestamp
  updatedAt: string;             // ISO timestamp

  // Unlimited hierarchy fields (v1.8.0)
  parentId?: string;             // Parent task ID for unlimited nesting (NEW)
  level?: number;                // Computed hierarchy level (0, 1, 2, etc.) (NEW)

  // Enhanced metadata fields (from v1.7.0)
  dependsOn?: string[];          // Task dependencies (IDs of prerequisite tasks)
  priority?: number;             // Priority level (1-10, where 10 is highest)
  complexity?: number;           // Complexity estimate (1-10, where 10 is most complex)
  status?: string;               // Enhanced status: 'pending' | 'in-progress' | 'blocked' | 'done'
  tags?: string[];               // Tags for categorization and filtering
  estimatedHours?: number;       // Estimated time to complete (hours)
  actualHours?: number;          // Actual time spent (hours)
}

レガシーサブタスク（v1.8.0 で非推奨）

個別の Subtask インターフェースは、統合された Task モデルに置き換えられました。レガシーサブタスクは、parentId フィールドを持つタスクに自動的に移行されます。これにより、すべての階層で豊富な機能を維持しながら、階層の深さを無制限にできます。

メモリ

{
  id: string;                    // Unique identifier
  title: string;                 // Short title for file naming (max 50 characters)
  content: string;               // Detailed memory content/text (no limit)
  metadata: Record<string, any>; // Flexible metadata object
  createdAt: string;            // ISO timestamp
  updatedAt: string;            // ISO timestamp
  category?: string;            // Optional categorization
}

ワークフローの例

1. プロジェクトを作成する

   Use create_project with:
   - workingDirectory="/path/to/your/project"
   - name="Website Redesign"
   - description="Complete overhaul of company website"
   

2. 拡張タスクを追加する

   Use create_task with:
   - workingDirectory="/path/to/your/project"
   - name="Design mockups"
   - details="Create wireframes and high-fidelity designs"
   - projectId="[project-id-from-step-1]"
   - priority=8 (high priority)
   - complexity=6 (above average complexity)
   - status="pending"
   - tags=["design", "ui", "mockups"]
   - estimatedHours=16
   

3. タスクを細分化する

   Use create_subtask with:
   - workingDirectory="/path/to/your/project"
   - name="Create wireframes"
   - details="Sketch basic layout structure"
   - taskId="[task-id-from-step-2]"
   

4. 進捗を追跡する

   Use update_task and update_subtask to mark items as completed
   Use list_projects, list_tasks, and list_subtasks to view progress
   (All with workingDirectory parameter)
   

エージェントのメモリを使ったワークフロー

1. メモリを作成する

   Use create_memory with:
   - workingDirectory="/path/to/your/project"
   - title="User prefers concise technical responses"
   - content="The user has explicitly stated they prefer concise responses with technical explanations. They value brevity but want detailed technical information when relevant."
   - metadata={"source": "conversation", "confidence": 0.9}
   - category="user_preferences"
   

2. メモリを検索する

   Use search_memories with:
   - workingDirectory="/path/to/your/project"
   - query="user preferences responses"
   - limit=5
   - threshold=0.3
   - category="user_preferences"
   

3. 一覧表示と管理

   Use list_memories to view all memories
   Use update_memory to modify existing memories (title, content, metadata, category)
   Use delete_memory to remove outdated memories
   (All with workingDirectory parameter)
   

📖 クイックスタート：エージェントのメモリについて、手順ごとのガイドは docs/QUICK_START_MEMORIES.md をご覧ください。

データストレージ

• プロジェクト固有：各作業ディレクトリは、それぞれ独立したタスクデータとメモリデータを持ちます
• ファイルベース：タスクデータは .agentic-tools-mcp/tasks/ に、メモリデータは .agentic-tools-mcp/memories/ に保存されます
• Git で追跡可能：すべてのデータをプロジェクトコードと一緒にコミットできます
• 永続的：すべてのデータはサーバーの再起動後も保持されます
• アトミック：データの破損を防ぐため、すべての操作はアトミックに行われます
• JSON ストレージ：効率的なメモリ整理のためのシンプルなファイルベースのストレージ
• バックアップに適した形式：バックアップや移行が簡単なシンプルなファイルベースのストレージ

ストレージ構造

your-project/
├── .agentic-tools-mcp/
│   ├── tasks/              # Task management data for this project
│   │   └── tasks.json      # Projects, tasks, and subtasks data
│   └── memories/           # JSON file storage for memories
│       ├── preferences/    # User preferences category
│       │   └── User_prefers_concise_technical_responses.json
│       ├── technical/      # Technical information category
│       │   └── React_TypeScript_project_with_strict_ESLint.json
│       └── context/        # Context information category
│           └── User_works_in_healthcare_needs_HIPAA_compliance.json
├── src/
├── package.json
└── README.md

作業ディレクトリのパラメーター

すべての MCP ツールには、次の項目を指定する workingDirectory パラメーターが必要です。

• .agentic-tools-mcp/ フォルダーの保存先（プロジェクト固有モードの場合）
• アクセスするプロジェクトのタスクデータとメモリデータ
• 複数のプロジェクトで、それぞれ別のタスクリストとメモリストアを使用できるようにします

注：サーバーを --claude フラグ付きで起動した場合、workingDirectory パラメーターは無視され、代わりにグローバルなユーザーディレクトリ（macOS/Linux では ~/.agentic-tools-mcp/、Windows では C:\Users\{username}\.agentic-tools-mcp\）が使用されます。

プロジェクト固有のストレージのメリット

• Git との統合：タスクデータとメモリデータをコードと一緒にコミットできます
• チームでの協働：バージョン管理を通じて、タスクリストとエージェントのメモリを共有できます
• プロジェクトの分離：各プロジェクトは独自のタスク管理システムとメモリシステムを持ちます
• 複数プロジェクトでのワークフロー：メモリを分離したまま、複数のプロジェクトを同時に進められます
• バックアップと移行：ファイルベースのストレージはコードと一緒に持ち運べます
• テキスト検索：内容ベースのシンプルなメモリ検索で、適切なコンテキストをインテリジェントに取得できます
• エージェントの継続性：セッションやデプロイをまたいでエージェントのメモリを保持できます

エラー処理

• 検証：すべての入力を検証し、包括的なエラーメッセージを表示します
• ディレクトリの検証：作業ディレクトリが存在し、アクセス可能であることを確認します
• 参照整合性：カスケード削除により、孤立したタスクやサブタスクの発生を防ぎます
• 名前の一意性：スコープ内（プロジェクト／タスク）で名前が一意になるようにします
• 確認：破壊的な操作には明示的な確認が必要です
• 正常な縮退動作：トラブルシューティングに役立つ詳細なエラーメッセージを表示します
• ストレージエラー：ストレージの初期化に失敗した場合に、明確なメッセージを表示します

開発

ソースからのビルド

git clone <repository>
cd agentic-tools-mcp
npm install
npm run build
npm start

プロジェクト構成

src/
├── features/
│   ├── task-management/
│   │   ├── tools/           # MCP tool implementations
│   │   │   ├── projects/    # Project CRUD operations
│   │   │   ├── tasks/       # Task CRUD operations
│   │   │   └── subtasks/    # Subtask CRUD operations
│   │   ├── models/          # TypeScript interfaces
│   │   └── storage/         # Data persistence layer
│   └── agent-memories/
│       ├── tools/           # Memory MCP tool implementations
│       │   └── memories/    # Memory CRUD operations
│       ├── models/          # Memory TypeScript interfaces
│       └── storage/         # JSON file storage implementation
├── server.ts            # MCP server configuration
└── index.ts             # Entry point

トラブルシューティング

よくある問題

「作業ディレクトリが存在しません」

• パスが存在し、アクセス可能であることを確認してください
• 信頼性を高めるため、絶対パスを使用してください
• ディレクトリのアクセス権限を確認してください

「テキスト検索で結果が返されない」（エージェントメモリ）

• 別のキーワードやフレーズを試してください
• メモリに検索語句が含まれていることを確認してください
• クエリの内容がメモリの内容と一致していることを確認してください

「メモリファイルが見つかりません」（エージェントメモリ）

• 作業ディレクトリが存在し、書き込み可能であることを確認してください
• .agentic-tools-mcp/memories ディレクトリが作成されていることを確認してください

バージョン履歴

詳細なバージョン履歴とリリースノートについては、CHANGELOG.md を参照してください。

現在のバージョン：1.8.0

• 🚀 新機能：統合タスクモデル：無制限の階層をサポートする単一のタスクインターフェース
• 🚀 新機能：無制限の階層：タスク → サブタスク → サブサブタスク → 無限の深さでのネスト
• 🚀 新機能：自動移行：3 レベルモデルから無制限階層モデルへシームレスにアップグレード
• 🚀 新機能：強化されたツリー表示：レベルインジケーターと無制限の深さに対応した階層の可視化
• 🚀 新機能：階層ツール：無制限の階層管理に対応する move_task、migrate_subtasks
• ✅ すべてのレベルで豊富な機能：すべてのタスクで、優先度、複雑度、依存関係、タグ、時間追跡を利用できます
• ✅ 強化されたタスク管理：依存関係、優先度、複雑度、ステータス、タグ、時間追跡を含む豊富なメタデータ
• ✅ 高度な AI エージェントツール：PRD の解析、タスクの推奨、複雑度の分析、進捗の推定、調査ガイダンス
• ✅ インテリジェントなタスク依存関係：階層全体にわたる依存関係の検証とワークフロー管理
• ✅ 優先度と複雑度のシステム：すべてのレベルで 1～10 の尺度による優先順位付けと複雑度の推定
• ✅ 強化されたステータスワークフロー：pending → in-progress → blocked → done のステータス追跡
• ✅ タグベースの整理：柔軟な分類とフィルタリングのシステム
• ✅ 時間追跡：プロジェクト計画に必要な見積もり時間と実績時間
• ✅ ハイブリッド調査の統合：AI エージェント向けのメモリキャッシュを利用したウェブ調査
• ✅ 無制限の階層構成に対応した完全なタスク管理システム
• ✅ タイトルとコンテンツのアーキテクチャ、JSON ファイルストレージを備えたエージェントメモリ
• ✅ 関連度スコアリングを備えたインテリジェントな複数フィールド検索
• ✅ 包括的な MCP ツールを備えたプロジェクト固有のストレージ
• ✅ Claude Desktop 用の --claude フラグを使用したグローバルディレクトリモード
• ✅ VS Code 拡張機能エコシステムとの統合

謝辞

この MCP サーバーを実現しているオープンソースコミュニティと、以下のプロジェクトに感謝します。

コアテクノロジー

• @modelcontextprotocol/sdk - MCP サーバー実装の基盤
• Node.js File System - メモリの永続化に対応する、信頼性の高いファイルベースのストレージ
• TypeScript - 型安全な JavaScript 開発
• Node.js - JavaScript ランタイム環境

開発と検証

• Zod - 堅牢な入力処理を実現する、TypeScript ファーストのスキーマ検証
• ESLint - コード品質と一貫性の維持
• Prettier - コードのフォーマット

ファイルストレージと検索

• JSON - メモリの保存に使用する、シンプルで人が読みやすいデータ形式です
• テキスト検索 - メモリファイル全体を対象とした、効率的なコンテンツベースの検索です

特別な謝辞

• オープンソースコミュニティ - このプロジェクトを実現するツールやライブラリを作成してくださったことに感謝します

ライセンス

MIT License - 詳細は LICENSE ファイルをご覧ください。

コントリビューション

コントリビューションを歓迎します！お気軽にイシューやプルリクエストを送信してください。

開発環境のセットアップ

git clone <repository>
cd agentic-tools-mcp
npm install
npm run build
npm start

関連プロジェクト

🖥️ VS Code 拡張機能

Agentic Tools MCP Companion - この MCP サーバーに GUI インターフェースを提供する、使いやすい VS Code 拡張機能です。

主な機能：

• 🎯 視覚的なタスク管理：拡張されたタスクメタデータフォームを備えた、使いやすい GUI
• 📝 拡張フォーム：優先度、複雑さ、ステータス、タグ、時間の追跡
• 🎨 視覚的なインジケーター：ステータスの絵文字、優先度バッジ、複雑さのインジケーター
• 📊 詳細なツールチップ：ホバー時にタスク情報をすべて表示
• 🔄 リアルタイム同期：MCP サーバーのデータと即時に同期
• � レスポンシブデザイン：さまざまな画面サイズで使える、適応型フォーム

次のような用途に最適です：

• 視覚的なタスク管理と計画
• GUI インターフェースを好むチーム
• 詳細なタスクメタデータを必要とするプロジェクトマネージャー
• VS Code でタスクを見やすく整理したい方

サポート

問題や質問については、GitHub のイシュートラッカーをご利用ください。

ドキュメント

• 📖 API リファレンス - ツールに関する包括的なドキュメント
• 🧠 エージェントメモリガイド - メモリシステムの包括的なガイド
• 🚀 クイックスタート：メモリ - エージェントメモリを使い始める
• 📋 変更履歴 - バージョン履歴とリリースノート

ヘルプの利用方法

• 🐛 GitHub のイシューからバグを報告
• 💡 GitHub のディスカッションから機能をリクエスト
• 🖥️ VS Code 拡張機能の問題：拡張機能固有の問題は agentic-tools-mcp-companion から報告