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许可证。