agent-never-give-up

Agent Never Give Up MCP

これは、AI コーディングエージェント向けの「脱出ガイド」として機能する MCP サーバーです。

人の助けを借りずにエージェントが行き詰まりを解消できるよう、構造化された思考プロトコルを提供します。

以下の図は、エージェントがこのサーバーを呼び出すべきタイミングと、その結果として受け取る内容を示しています。

graph TD
    %% 1. The Normal Loop
    UserLoop["<b>User Query & Agent Loop</b><br/>(Claude Code / Windsurf / Cursor)<br/>Agent executing tasks..."]

    %% 2. The Problem (Triggers)
    subgraph Triggers ["Agent Gets Stuck (Trigger State)"]
        direction TB
        S1["Circular Reasoning"]
        S2["Bug Fix Fails"]
        S3["Missing Info"]
        S4["Analysis Paralysis"]
        S5["Unclear 'Done' State"]
    end

    %% Flow: Loop -> Stuck
    UserLoop -.->|"⚠️ Detects Issue<br/>(Inner Loop Stall)"| Triggers

    %% 3. The Solution (MCP Call)
    subgraph MCP ["Agent Never Give Up MCP"]
        direction TB
        T1(logic-is-too-complex)
        T2(bug-fix-always-failed)
        T3(missing-requirements)
        T4(analysis-too-long)
        T5(unclear-acceptance-criteria)
    end

    %% Mapping Triggers to Tools
    S1 -->|Call| T1
    S2 -->|Call| T2
    S3 -->|Call| T3
    S4 -->|Call| T4
    S5 -->|Call| T5

    %% 4. The Response
    MCP -->|Returns| R1["<b>Metacognitive Protocol</b><br/>Structured markdown to:<br/>1. Re-anchor goal<br/>2. Summarize failures<br/>3. Propose NEW strategy"]

    %% 5. The Outcome
    R1 --> Result["<b>Autonomous Recovery</b><br/>Agent unblocks itself &<br/>resumes execution<br/>(No Human Hand-off)"]

    %% Cycle back to loop
    Result -.->|"Resumes Loop"| UserLoop

    %% Styling
    classDef loop fill:#e1f5fe,stroke:#01579b,stroke-width:2px;
    classDef trigger fill:#ffebee,stroke:#b71c1c,stroke-width:2px;
    classDef tool fill:#fff3e0,stroke:#e65100,stroke-width:2px;
    classDef response fill:#e8f5e9,stroke:#1b5e20,stroke-width:2px;
    
    class UserLoop loop;
    class S1,S2,S3,S4,S5 trigger;
    class T1,T2,T3,T4,T5 tool;
    class R1,Result response;

機能

• /mcp エンドポイントにある リモート MCP サーバー（Streamable HTTP 仕様に準拠）
• 2 層のシナリオ構成：
  • コアシナリオ（MCP ツールとして自動登録）：
    • logic-is-too-complex – 循環した推論や、複雑になりすぎたロジック向け
    • bug-fix-always-failed – バグ修正の試行が何度も失敗する場合向け
    • missing-requirements – 要件が不明確、または不足している場合向け
    • lost-main-objective – 現在の作業が当初の目標から逸れていると感じる場合向け
    • scope-creep-during-task – 変更が当初のタスク範囲を超えて広がっている場合向け
    • long-goal-partially-done – 複数の手順からなるタスクで、残りの作業を忘れてしまった場合向け
    • strategy-not-working – 同じアプローチが何度も失敗する場合向け
  • 拡張シナリオ（list_scenarios で検出し、get_prompt から利用）：
    • analysis-too-long – 分析に時間をかけすぎている場合向け
    • unclear-acceptance-criteria – 受け入れ基準が定義されていない場合向け
    • wrong-level-of-detail – 適切でない抽象度で作業している場合向け
    • constraints-cant-all-be-met – 要件や制約が互いに矛盾している場合向け
    • blocked-by-environment-limits – ロジックの問題ではなく、環境によって妨げられている場合向け
• 検出ツール：
  • list_scenarios – 各シナリオを階層（コア／拡張）とともに一覧表示
  • get_prompt – 任意のシナリオにアクセス（コアまたは拡張）
• デュアルモード対応：各ツールは static モードと sampling モードに対応
• Markdown ファイルによるコミュニティ投稿のプロンプト
• 公開かつ認証不要（v0）
• Cloudflare Workers へのデプロイ

設定

agent-never-give-up はクラウドホスト型の MCP サーバーであるため、ローカルへのインストールは不要です。お好みの AI ツールにサーバー設定を追加するだけで利用できます。

Cursor へのインストール

1. Cursor Settings > MCP を開きます。
2. + Add new global MCP server をクリックします。
3. 以下の設定を使用します（または ~/.cursor/mcp.json ファイルを直接編集します）。

{
  "mcpServers": {
    "agent-never-give-up": {
      "type": "http",
      "url": "https://agent-never-give-up-mcp.askman.dev/mcp",
      "note": "A 'Swiss Army knife' toolset to help agents recover from getting stuck"
    }
  }
}

Claude Desktop へのインストール

Claude Desktop 用にサーバーを設定するには、以下の場所にある設定ファイルを編集します。

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows: %APPDATA%\Claude\claude_desktop_config.json

mcpServers オブジェクトに次のエントリーを追加します。

{
  "mcpServers": {
    "agent-never-give-up": {
      "type": "http",
      "url": "https://agent-never-give-up-mcp.askman.dev/mcp"
    }
  }
}

Cline へのインストール

1. Cline を開き、MCP Servers アイコン（☰）をクリックします。
2. Remote Servers タブ（利用可能な場合）を選択するか、Configure MCP Servers をクリックします。
3. cline_mcp_settings.json ファイルを編集し、次の内容を追加します。

{
  "mcpServers": {
    "agent-never-give-up": {
      "type": "http",
      "url": "https://agent-never-give-up-mcp.askman.dev/mcp",
      "note": "A comprehensive suite of tools designed to keep agents persistent and unstuck"
    }
  }
}

Windsurf へのインストール

1. Windsurf を開きます。
2. File > Settings > Configure MCP Servers に移動します（または ~/.codeium/windsurf/mcp_config.json を編集します）。
3. サーバー設定を追加します。

{
  "mcpServers": {
    "agent-never-give-up": {
      "type": "http",
      "url": "https://agent-never-give-up-mcp.askman.dev/mcp"
    }
  }
}

開発

このプロジェクトへの貢献、またはローカルインスタンスの実行方法：

# Install dependencies
npm install

ローカルサーバーは http://localhost:8787/mcp で利用できます。

プロンプトへの貢献

プロンプトは prompts/ ディレクトリ内で、2 つの階層に分けて整理されています。

prompts/
├── core/                           # Core scenarios (auto-registered as tools)
│   ├── logic-is-too-complex/
│   │   └── tool.md
│   ├── bug-fix-always-failed/
│   │   └── tool.md
│   └── missing-requirements/
│       └── tool.md
└── extended/                       # Extended scenarios (via list_scenarios + get_prompt)
    ├── analysis-too-long/
    │   └── tool.md
    └── unclear-acceptance-criteria/
        └── tool.md

プロンプトファイル形式

各 tool.md ファイルは、YAML フロントマターと単一のプロトコル本文からなるシンプルな Markdown 形式に従います。

---
name: scenario_name
title: "Scenario Title"
description: "When / why the agent should call this tool, from the agent's perspective"
---

When you notice [the trigger condition], follow this exact protocol step by step.

## 1. First step title

1. Action item one.
2. Action item two.
3. Action item three.

Keep it concrete.

## 2. Second step title

...

## 3. Third step title

...

主な原則：

• description では、ツールを使用するタイミング（トリガー条件）を説明します
• 本文は、番号付きセクションで構成される単一のプロトコルです
• 各セクションには、2～6 個の具体的な手順を記載します
• ドメイン固有の詳細ではなく、思考の進め方に焦点を当てます
• システムプロンプト／ユーザープロンプトのテンプレートセクションは設けず、実行可能なプロトコルを 1 つだけ記載します

効果的なプロンプトの作成方法について詳しくは、prompts/AGENTS.md を参照してください。

新しいシナリオの追加

シナリオは、prompts/ ツリーと、生成された src/prompts/generated-scenarios.ts および src/types/generated-scenarios.ts のファイルから自動検出されます。TypeScript ファイルを手動で編集する必要はありません。プロンプトを追加して再生成するだけです。

コアシナリオ（ツールとして自動登録）：

1. 新しいディレクトリを作成します：prompts/core/{scenario_name}/（/^[a-z0-9]+(-[a-z0-9]+)*$/ に一致する必要があります）。
2. 上記の形式に従って tool.md ファイルを追加します。
3. npm run generate:scenarios を実行して、型と検出データを再生成します。

拡張シナリオ（get_prompt から利用可能）：

1. 新しいディレクトリを作成します：prompts/extended/{scenario_name}/（上記と同じ命名規則です）。
2. 上記の形式に従って tool.md ファイルを追加します。
3. npm run generate:scenarios を実行して、型と検出データを再生成します。

デプロイ

# Deploy to Cloudflare Workers
npm run deploy

デプロイ後、MCP エンドポイントは次のようになります： https://agent-never-give-up-mcp.<account>.workers.dev/mcp

ライセンス

MIT