agent-never-give-up

Agent 永不放弃 MCP

这是一个 MCP 服务，充当 AI 编码 Agent 的“脱困指南”。

它提供结构化思考协议，帮助 Agent 在没有人工协助的情况下摆脱困境。

下图展示了 Agent 应在何时调用此服务，以及调用后会收到什么：

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 规范）
• 双层场景组织：
  • 核心场景（自动注册为直接 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 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/ 目录中按两个层级组织：

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 frontmatter 和一个协议正文：

---
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 个具体步骤
• 重点关注如何思考，而非特定领域的细节
• 不要设置 system prompt / user prompt 模板章节，只需提供一个可执行的协议

有关如何编写有效提示词的详细指南，请参阅 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