Agent Never Give Up MCP

🚀 Agent Never Give Up MCP

這是一個MCP服務器，它為AI編碼智能體充當“脫困指南”。它提供結構化的思維協議，幫助智能體在無需人工干預的情況下自行擺脫困境。

智能體調用服務器的流程示意圖

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端點，符合可流式HTTP規範。
• 兩層場景組織：
  • 核心場景（自動註冊為直接的MCP工具）：
    • logic-is-too-complex — 用於處理循環推理或過於複雜的邏輯。
    • bug-fix-always-failed — 用於處理反覆失敗的Bug修復嘗試。
    • 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設置 > MCP。
2. 點擊**+ 添加新的全局MCP服務器**。
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服務器圖標（☰）。
2. 選擇遠程服務器選項卡（如果可用）或點擊配置MCP服務器。
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. 轉到文件 > 設置 > 配置MCP服務器（或編輯~/.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可用。

部署示例

# Deploy to Cloudflare Workers
npm run deploy

部署後，你的MCP端點將是：https://agent-never-give-up-mcp.<account>.workers.dev/mcp

📚 詳細文檔

貢獻提示

提示信息在prompts/目錄中分為兩層組織：

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文件遵循簡單的Markdown格式，包含YAML前置元數據和單個協議主體：

---
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個具體步驟。
• 專注於如何思考，而非特定領域的細節。
• 沒有系統提示/用戶提示模板部分 —— 只有一個可操作的協議。

有關編寫有效提示的詳細指南，請參閱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以重新生成類型和發現數據。

📄 許可證

本項目採用MIT許可證。