Skip to main content
Glama
Panda-Young

Gopeed MCP Server

Gopeed MCP Server

⚠️ 本仓库已停止维护(Archived / No Longer Maintained)

Gopeed 官方已在 v2.0.0-beta.1 中内置原生 MCP 支持,本项目作为第三方替代方案已完成历史使命,不再继续维护。

请直接使用 Gopeed 官方内置的 MCP 能力,无需再安装本 Server:

  • 官方在 Gopeed 2.0 中提供了内置的 MCP 端点,AI Agent 可直连并管理下载任务;

  • 官方内置工具集(9 个)覆盖了本项目的主要能力: resolve_task、create_task、list_tasks、get_task、get_task_status、get_task_stats、pause_task、continue_task、delete_task;

  • 相比本项目的 pause / resume 两个动作,官方新增了 resolve_task(创建前预解析资源)、get_task_status(轻量运行状态)、get_task_stats(HTTP 连接数 / BT 做种等协议级统计)等更完整的能力。

接入方式:请参阅 Gopeed 官方文档与 官方仓库 README 的 “AI Integration” 章节,按其说明获取 MCP 端点地址并配置到你的 MCP 客户端。

本仓库代码保留可查、可自行 fork,但不再接受 Issue / PR,也不会再发布新版本或适配 Gopeed 2.0 的 API 变更。下文文档仅作历史存档,其中的用法可能在 Gopeed 新版本上失效。


以下为原始说明文档(存档,不再更新)。

一个基于 Model Context Protocol (MCP) 的 Server,让你能在各种 AI Agent / 智能体中通过自然语言控制 Gopeed 下载管理器。它遵循标准 MCP 协议,可无缝接入任意兼容 MCP 的客户端,例如 VS Code Copilot Chat、WorkBuddy、Trae 等。

关于 Gopeed:本项目的被控对象是开源下载管理器 Gopeed(由 GopeedLab 维护,采用 GPL-3.0 许可证)。本 Server 仅通过 Gopeed 公开的 REST API 与之通信,不修改、不嵌入其任何源代码,因此本仓库以 MIT 许可证独立发布。使用前请先安装并运行 Gopeed 本体。

Related MCP server: Taskboard MCP Server

功能介绍

本节为历史存档内容。请优先使用 Gopeed 官方内置 MCP(见文首说明)。

本 MCP Server 封装了 Gopeed 的 REST API,提供以下 10 个工具:

工具

说明

create_download_task

创建下载任务,支持自定义文件名和并发连接数

list_tasks

列出所有下载任务,可按状态过滤

get_task_detail

获取单个任务的详细信息

pause_task

暂停指定任务

resume_task

恢复(继续)指定任务

delete_task

删除单个任务,可选同时删除已下载文件

delete_completed_tasks

删除所有已完成的历史任务

delete_done_tasks

delete_completed_tasks 的别名

get_config

获取 Gopeed 当前配置(下载目录、连接数、代理等)

update_config

更新 Gopeed 配置(只传需要修改的字段)

环境要求

  • Python 3.10+

  • Gopeed 已安装并运行(API 端口每次启动随机分配,无需手动指定)

  • 任意兼容 MCP 的 AI Agent / 智能体客户端(如 VS Code Copilot Chat、WorkBuddy、Trae 等)

安装步骤

  1. 进入项目目录:

    cd gopeed-mcp-server
  2. (推荐)创建虚拟环境:

    python -m venv .venv
    # Windows
    .venv\Scripts\activate
    # macOS / Linux
    source .venv/bin/activate
  3. 安装依赖(二选一):

    • 方式 A:从源码安装依赖

      pip install -r requirements.txt
    • 方式 B:作为 Python 包安装(推荐,可用于 uvx 一键启动)

      pip install gopeed-mcp-server

      安装后会得到 gopeed-mcp-server 命令,可用 uvx gopeed-mcp-server 直接启动。

  4. (可选)配置环境变量。复制 .env.example 为 .env 并按需修改:

    copy .env.example .env

    可用环境变量:

    • GOPEED_API_URL:Gopeed API 地址。默认 http://127.0.0.1:7766/api/v1(端口 7766 为默认固定端口)。若你的 Gopeed 使用随机端口,可留空端口部分(如 http://127.0.0.1/api/v1),server 会自动发现 Gopeed 实际端口。

    • GOPEED_API_TOKEN:API 令牌(可选,Gopeed 配置了令牌时需要)

    • GOPEED_TIMEOUT:请求超时秒数,默认 10

客户端配置方法

以下以 VS Code Copilot Chat 为例,其他兼容 MCP 的客户端(WorkBuddy、Trae 等)配置方式类似。

手动配置 mcp.json

VS Code 1.99+ 使用专用的 mcp.json(而不是 settings.json 的 mcpServers 字段)。

  1. 按 Ctrl+Shift+P,运行 MCP: Open User Configuration(或在工作区创建 .vscode/mcp.json)。

  2. 添加如下配置(使用 uvx 启动,无需本地路径):

    {
      "servers": {
        "gopeed": {
          "command": "uvx",
          "args": ["gopeed-mcp-server"],
          "env": {
            "GOPEED_API_URL": "http://127.0.0.1:7766/api/v1"
          }
        }
      }
    }

    若未发布到 PyPI,可改用本地源码方式:

    {
      "servers": {
        "gopeed": {
          "command": "python",
          "args": ["-m", "gopeed_mcp_server"],
          "env": {
            "GOPEED_API_URL": "http://127.0.0.1:7766/api/v1"
          }
        }
      }
    }

    注意:

    • GOPEED_API_URL 默认使用 http://127.0.0.1:7766/api/v1(端口 7766 为固定端口);若使用随机端口可留空端口部分,server 会自动发现 Gopeed 当前监听端口。

    • 如果 Gopeed 配置了 API 令牌,在 env 中添加 "GOPEED_API_TOKEN": "你的令牌"。

    • Windows 沙箱(sandbox)目前不可用,本地 stdio server 直接运行。

  3. 保存 mcp.json,重启 VS Code(或 Developer: Reload Window)。

  4. 验证配置:打开 Copilot Chat,输入 @gopeed 或直接描述需求,Copilot 应能识别并调用 Gopeed 工具。也可在 MCP 面板中查看 gopeed server 状态。

使用示例

在任意兼容 MCP 的客户端中,你可以用自然语言这样说:

你说的话

触发的操作

"帮我下载这个文件:https://example.com/file.zip"

创建下载任务

"下载 https://example.com/video.mp4,文件名改成我的视频.mp4,用 32 个连接"

创建任务并指定文件名和并发数

"看看现在有哪些下载任务"

列出所有任务

"显示正在下载的任务"

按 running 状态过滤任务列表

"查看任务 abc123 的详细信息"

获取任务详情

"暂停任务 abc123"

暂停任务

"继续任务 abc123"

恢复任务

"删除任务 abc123"

删除任务(保留文件)

"删除任务 abc123,连文件一起删掉"

强制删除任务和文件

"删除已完成的历史任务"

删除所有已完成任务

"清理历史下载记录,连文件也删掉"

强制清理所有已完成任务及文件

"Gopeed 当前配置是什么?"

获取配置

"把并发连接数改成 32"

更新配置

"把下载目录改成 D:\Downloads"

更新下载目录

"启用代理" / "关闭代理"

更新代理开关

项目结构

gopeed-mcp-server/
├── src/
│   └── gopeed_mcp_server/ # Python package 源码
│       ├── __init__.py    # 包入口,导出公共 API
│       ├── __main__.py    # 支持 python -m gopeed_mcp_server 启动
│       ├── config.py      # 配置管理(从环境变量读取)
│       ├── constants.py   # 状态常量定义
│       ├── client.py      # Gopeed REST API 客户端封装
│       ├── transport.py   # HTTP 传输层(自动重发现)
│       ├── discovery.py   # 端口自动发现逻辑
│       ├── exceptions.py  # 异常类型定义
│       └── server.py      # MCP Server 主入口,定义所有 MCP Tools
├── pyproject.toml         # 打包配置(提供 gopeed-mcp-server 命令)
├── requirements.txt       # Python 依赖
├── .env.example           # 环境变量示例
├── icon.png               # 包 / 仓库图标
└── README.md              # 本文件

故障排查

1. Copilot Chat 无法调用 Gopeed 工具

  • 确认 mcp.json 中 servers.gopeed 配置正确(uvx gopeed-mcp-server 或本地 python -m gopeed_mcp_server),路径使用正斜杠或双反斜杠 \\。

  • 若使用本地源码方式,确认 command 指向可运行的 Python(如 ...\.venv\Scripts\python.exe 或裸 python),而非错误路径。

  • 重启 VS Code 后再试。

  • 在 VS Code 中打开 Output 面板,选择 MCP 通道查看 gopeed server 的日志输出。

2. 提示"无法连接到 Gopeed"

  • 确认 Gopeed 已启动并正在运行。

  • Gopeed 每次重启会随机分配 API 端口,本 server 默认自动发现当前端口;若 GOPEED_API_URL 写死了旧端口会失效,建议改为留空端口的 http://127.0.0.1/api/v1。

  • 检查防火墙是否阻止了本地回环连接;若系统启用了代理,localhost 请求可能被拦截返回 503,本 server 已对本地请求禁用代理。

3. 提示"Gopeed 业务错误"或"HTTP 401/403"

  • Gopeed 可能配置了 API 访问令牌,需要在 env 中设置 GOPEED_API_TOKEN。

  • 在 Gopeed Web UI 的设置中查看是否启用了令牌认证。

4. Python 依赖安装失败

  • 确保 Python 版本 >= 3.10:python --version

  • 升级 pip:pip install --upgrade pip

  • 使用国内镜像源:pip install -r requirements.txt -i https://pypi.tuna.tsinghua.edu.cn/simple

5. 手动测试 Gopeed API 连通性

Gopeed 端口随机,先找到当前端口再用 curl 测试:

# Windows:通过 netstat 找到 gopeed 监听的回环端口
netstat -ano | findstr "LISTENING" | findstr "gopeed"

# 假设查到端口为 12345,则:
curl http://127.0.0.1:12345/api/v1/config
curl http://127.0.0.1:12345/api/v1/tasks

如果 curl 能正常返回 JSON 数据(含 "code":0),说明 Gopeed API 正常,问题出在 MCP Server 配置或 Python 环境。

许可证

本项目(Gopeed MCP Server)以 MIT 许可证发布,详见 LICENSE。

被控对象 Gopeed 本身是独立的开源项目,采用 GPL-3.0 许可证(© GopeedLab 及其贡献者)。本 Server 仅通过网络调用其公开 REST API 进行集成,不构成对 Gopeed 源代码的修改或衍生,亦不随本仓库分发 Gopeed 的任何代码。如使用 Gopeed 本体,请遵守其对应的许可证条款。

发布与上架

⚠️ 本节已作废:项目停止维护,不再向 PyPI / Glama / Smithery 等渠道发布新版本。

本 server 曾发布到以下渠道(历史记录):

  • GitHub(已公开):https://github.com/Panda-Young/gopeed-mcp-server —— 仓库即发布页,按上面的 mcp.json 片段手动添加即可使用。

  • PyPI(已发布):pip install gopeed-mcp-server 或直接 uvx gopeed-mcp-server,见 https://pypi.org/project/gopeed-mcp-server/ 。

  • Glama:打开 https://glama.ai/mcp/register ,粘贴本仓库 URL,会自动读取仓库根的 mcp.json。

  • Smithery:本地 stdio server 用 CLI 发布(非网页表单)。安装 @smithery/cli 后,在仓库目录执行 smithery login 再 smithery mcp publish . -n @Panda-Young/gopeed-mcp-server(会读取 smithery.yaml)。

  • VS Code MCP Gallery:VS Code 内置的 MCP Gallery 目前为微软托管的精选列表,没有公开的投稿入口,个人开发者暂无法直接上架。用户可从上面的 GitHub / PyPI / Glama / Smithery 任一渠道获取并手动配置到 mcp.json。

  • 手动分享:任何已安装本包的环境,把上面的 mcp.json 片段加入 mcp.json 即可使用。

发布新版本到 PyPI

⚠️ 已作废:维护者不再发布新版本。以下步骤仅在你 fork 后自行发布时参考。

修改 pyproject.toml 中的 version 后,重新构建并上传:

python -m build
twine upload dist/*

上传凭证请勿写入本仓库。推荐在用户目录 ~/.pypirc 配置 [pypi] 的 username = __token__ 与 password,或使用环境变量 TWINE_USERNAME / TWINE_PASSWORD。令牌从 https://pypi.org/manage/account/token/ 获取。

Available Tools

10 tools
create_download_taskA

Create a new download task.

Args: url: Download URL (HTTP/HTTPS/Magnet etc). name: Optional save filename. connections: Optional HTTP concurrent connections count.

ParametersJSON Schema
NameRequiredDescriptionDefault
urlYes
nameNo
connectionsNo

Output Schema

ParametersJSON Schema
NameRequiredDescription
resultYes

TDQS

A3.7/5.0
Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, so the description carries the full burden of behavioral disclosure. It states the action but does not mention side effects, whether downloading starts immediately, queueing behavior, idempotency, or any error conditions. The only extra detail is accepted URL schemes, which is helpful but leaves many behavioral aspects unclear.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is compact and front-loaded with the core purpose. The Args block is organized and each line adds necessary information without redundancy. There is no filler or repetition.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

The tool is relatively simple and an output schema exists, so return values are covered. However, the description lacks behavioral details such as whether the task starts automatically, any authentication requirements, or what happens when the URL is invalid. These gaps make it only partially complete for an agent deciding how to invoke it correctly.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 0%, but the description compensates by explaining all three parameters: url with protocol examples, name as optional save filename, and connections as optional HTTP concurrent connection count. It adds meaning beyond the raw schema types, though it could go further with constraints like accepted values or defaults.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description states a specific verb+resource: 'Create a new download task.' This directly distinguishes it from siblings like list_tasks, pause_task, resume_task, and delete_task. The action is unambiguous and immediately identifies the tool's role.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description implies when to use the tool (to create a download task) but does not explicitly discuss exclusions, prerequisites, or alternatives. With siblings covering list/pause/resume/delete/config operations, the need to articulate when not to use this tool is minor, but the guidance is still mostly implicit rather than explicit.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

delete_completed_tasksA

Delete all completed historical download tasks.

Args: force: Also delete downloaded files for each completed task.

ParametersJSON Schema
NameRequiredDescriptionDefault
forceNo

Output Schema

ParametersJSON Schema
NameRequiredDescription
resultYes

TDQS

A3.6/5.0
Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations, the description carries the behavioral burden. It correctly discloses that `force` will also delete downloaded files, but it does not mention irreversibility, confirmation behavior, or whether active/incomplete tasks are protected. A deletion tool with no annotation coverage should state these caveats.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is short, front-loaded with the main action, and includes only the necessary `force` clarification. Every sentence earns its place; there is no redundant filler.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

The tool is simple and has an output schema, so return values need not be explained, but the missing distinction from `delete_done_tasks` and the undefined term 'historical' prevent an agent from being fully confident about scope. A sentence clarifying prerequisites or irreversibility would make the definition complete.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters5/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The only parameter, `force`, is a bare boolean in the schema with 0% schema description coverage. The description fully compensates by explaining that passing force also deletes the downloaded files for each completed task.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description states a specific action ('Delete all') and a clear target ('completed historical download tasks'), so an agent can understand what the tool does. However, it does not differentiate from the sibling `delete_done_tasks`, which appears to cover the same or overlapping concept, so it stops short of a 5.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

No guidance is given about when to prefer this tool over `delete_task`, `delete_done_tasks`, or any other sibling. The phrase 'completed historical' only implies the selection criteria; it does not state exclusions or point to alternatives.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

delete_done_tasksC

Alias for deleting completed download tasks.

ParametersJSON Schema
NameRequiredDescriptionDefault
forceNo

Output Schema

ParametersJSON Schema
NameRequiredDescription
resultYes

TDQS

C2.6/5.0
Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, so the description must disclose behavioral traits itself. It only says 'Alias for deleting completed download tasks,' which adds little beyond the tool name and does not explain side effects, irreversibility, or how the 'force' parameter alters behavior. The word 'Alias' implies equivalence with another operation but does not specify what that operation entails.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single sentence with no redundant wording and the main action is front-loaded. It is concise, though that conciseness comes at the cost of omitting parameter semantics. As a structure, it is clean, but not fully informative.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness2/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a deletion tool with no annotations and a parameter that is undocumented everywhere, the description is incomplete. It does not explain 'force', the difference from delete_completed_tasks, or any postconditions of the operation. The presence of an output schema helps with return values but not with these gaps.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters1/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 0%, and the description does not mention the 'force' boolean parameter at all. The input schema only provides a title and default, leaving the parameter's meaning entirely unexplained. The description fails to compensate for the missing parameter documentation.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the verb and resource: 'deleting completed download tasks.' It is not a tautology and an agent can tell what action occurs. However, it does not differentiate from the sibling tool delete_completed_tasks, and the word 'Alias' signals that it may be a duplicate rather than a distinct operation.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description gives general context—this affects completed download tasks—but it provides no explicit when-to-use or when-not-to-use guidance. Given the sibling delete_completed_tasks, there is no direction about which tool to prefer or how these two relate. The agent must infer the intended usage from the name alone.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

delete_taskB

Delete a download task.

Args: task_id: Task ID to delete. force: Also delete downloaded files (default: False).

ParametersJSON Schema
NameRequiredDescriptionDefault
forceNo
task_idYes

Output Schema

ParametersJSON Schema
NameRequiredDescription
resultYes

TDQS

B3.4/5.0
Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations provided, the description carries the full burden. It does disclose the important behavior that downloaded files are only deleted when force is true, which is valuable. However, it does not mention that deletion is irreversible, what happens to an actively running task, or what occurs to the downloaded files in the default case beyond leaving them intact.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a compact, front-loaded one-liner followed by a minimal two-item Args block. There is no filler or redundancy; every sentence contributes either purpose or parameter meaning.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a simple two-parameter delete tool, the core functional surface is covered, and an output schema exists to handle return values. The main gap is the lack of boundaries against sibling bulk-delete tools and any notes about side effects on active tasks or file permanence, which keeps it from being fully complete.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 0%, so the description must compensate, and it largely does: task_id is explained as the task to delete, and force is given the meaningful explanation 'Also delete downloaded files' with its default of False. This adds real semantics beyond the schema titles. The task_id explanation is somewhat obvious, so it is not a perfect 5.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states 'Delete a download task', which gives a specific verb and resource, and the Args section clarifies that it operates on the task identified by task_id. However, it does not explicitly distinguish itself from sibling tools like delete_completed_tasks or delete_done_tasks, so it stops short of 5.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

There is no guidance on when to use delete_task versus the sibling batch/cleanup deletion tools. The description does not mention preconditions, such as whether the task must be done or can be running, or when it is preferable to use one of the bulk delete tools. The only usage-adjacent info is the force default, which is more parameter semantics than usage guidance.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

get_configA

Get current Gopeed configuration.

ParametersJSON Schema
NameRequiredDescriptionDefault

No parameters

Output Schema

ParametersJSON Schema
NameRequiredDescription
resultYes

TDQS

A3.8/5.0
Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, so the description carries the behavioral transparency burden. 'Get current' implies a read-only snapshot without side effects, but the description does not explicitly state that it makes no changes or that no special permissions are required. It is adequate but not rich.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

A single sentence that directly states the operation and target. There is no filler or redundant information, making it appropriately concise for such a simple tool.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a zero-parameter getter with an output schema, the description is largely complete: it identifies what is retrieved. The only shortcoming is the lack of explicit usage guidance or an explicit read-only statement, but the low complexity limits the impact of these omissions.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The tool has zero parameters, so the description has no parameter semantics to add. The baseline of 4 applies because there is nothing missing.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description uses a specific verb ('Get') and names the exact resource ('current Gopeed configuration'). This clearly distinguishes it from sibling tools like update_config, which implies modification rather than retrieval.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description does not state when to use this tool versus alternatives. It implicitly suggests reading configuration, but there is no explicit guidance about using update_config when modification is needed or listing conditions for choosing this tool.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

get_task_detailA

Get detailed info for a specific task.

Args: task_id: Task ID (from list_tasks).

ParametersJSON Schema
NameRequiredDescriptionDefault
task_idYes

Output Schema

ParametersJSON Schema
NameRequiredDescription
resultYes

TDQS

A4.2/5.0
Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, so the description bears the burden of behavioral disclosure. The verb 'get' implies a read-only operation, and 'detailed info' indicates the nature of the response. However, it does not explicitly state that no side effects occur, or what happens for invalid/nonexistent task IDs. The output schema covers return structure, so the main gap is side-effect clarity.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is short, front-loaded with the primary purpose, and includes a clean Args structure. Every element earns its place—there is no filler, redundancy, or repetition of schema-only details.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a simple one-parameter tool with an existing output schema, the description is largely complete. It explains the purpose and parameter source, and the output schema handles return values. It could add explicit alternative routing, but that is not critical for a straightforward read operation.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 0%, but the description's Args block adds meaning by explaining that task_id is a Task ID and specifically referencing list_tasks as the source. This gives the agent provenance and context beyond the raw schema, which only provides a type and title. The single parameter is effectively documented.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description states a specific verb and resource: 'Get detailed info for a specific task.' This clearly distinguishes it from list_tasks and other sibling operations by focusing on retrieving details for a single task. An agent can tell immediately what this tool does and how it differs from the other task-related tools.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides a clear usage context by specifying that task_id should come from list_tasks, establishing a prerequisite workflow. It does not explicitly name alternatives or exclusions, but the purpose is unambiguous enough that an agent knows to use this when it needs details on an already-listed task.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

list_tasksA

List all download tasks, optionally filtered by status.

Args: status: Filter by status — ready, running, pause, done, error, unknown.

ParametersJSON Schema
NameRequiredDescriptionDefault
statusNo

Output Schema

ParametersJSON Schema
NameRequiredDescription
resultYes

TDQS

A4.6/5.0
Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, but the verb 'List' strongly signals a read-only operation with no side effects. The description also discloses the allowed status values. It does not mention pagination or ordering, but the output schema covers the return shape, so this is a minor gap.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is compact and front-loaded, stating the core behavior in the first sentence. The Args section is minimal and directly supplies the missing parameter semantics without unnecessary detail.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a simple list tool with one optional parameter and an output schema, the description covers purpose, filtering options, and accepted status values. Nothing essential for correct invocation is missing.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters5/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The input schema provides only a generic string/null status field with no enum or explanation. The description compensates by explicitly listing valid filter values and stating that filtering is optional, adding the necessary semantic meaning beyond the schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description uses a specific verb and resource: 'List all download tasks'. It also clarifies the optional status filter, so an agent immediately understands what the tool does and how it differs from task mutation or deletion siblings.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description clearly indicates this tool is for listing download tasks, with optional status filtering. It does not explicitly name alternatives such as get_task_detail, but the context is clear enough for an agent to infer when listing is appropriate.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

pause_taskB

Pause a download task.

Args: task_id: Task ID to pause.

ParametersJSON Schema
NameRequiredDescriptionDefault
task_idYes

Output Schema

ParametersJSON Schema
NameRequiredDescription
resultYes

TDQS

B3.1/5.0
Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are present, so the description carries the full burden of behavioral disclosure. It only states that the task is paused, without explaining state transitions, idempotency, reversibility, or side effects.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is compact and front-loaded with the action statement. The Args section is clear and contains no unnecessary prose.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a single-parameter command with an output schema, this is minimally adequate. However, it lacks behavioral context such as what happens if the task is already paused, whether it can be resumed, or how it relates to sibling operations.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 0%, but the description adds minimal meaning by stating that task_id is 'Task ID to pause.' This goes slightly beyond the schema's type-only definition, though it largely restates the parameter name and tool purpose.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description uses a specific verb and resource: 'Pause a download task.' This clearly identifies the tool's action and differentiates it by function from siblings like resume_task and delete_task, though it does not explicitly name alternatives.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

There is no guidance on when to use this tool versus alternatives such as resume_task or delete_task. No preconditions, edge cases, or contexts are given, so the agent must infer usage purely from the tool name and description.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

resume_taskA

Resume a paused download task.

Args: task_id: Task ID to resume.

ParametersJSON Schema
NameRequiredDescriptionDefault
task_idYes

Output Schema

ParametersJSON Schema
NameRequiredDescription
resultYes

TDQS

A4/5.0
Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, so the description carries the full disclosure burden. It states the main effect (resuming a paused task) and the precondition ('paused'), but does not describe error behavior, idempotency, or what happens if the task is not in a paused state. This is acceptable for a simple state-transition tool but not richly transparent.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is concise: a front-loaded action sentence followed by a minimal parameter explanation. Every sentence earns its place, with no filler or redundancy.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a one-parameter state-transition tool with an output schema, the description provides the essential action, precondition, and parameter meaning. It does not explicitly describe edge cases or its relationship to pause_task, but nothing critical is missing for an agent to invoke it correctly.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 0%, so the description must compensate. The args block explains that task_id is the 'Task ID to resume,' adding semantic meaning beyond the schema's bare string type and title. Since there is only one parameter and it is fully explained, this is sufficient.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb ('Resume') and a specific resource ('a paused download task'), which clearly distinguishes it from siblings like pause_task, delete_task, and list_tasks. The one-sentence definition is not a tautology and immediately conveys what the tool does.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The phrase 'a paused download task' implies the tool should be used when a task is already paused, and the sibling list includes pause_task as a counterpart. However, it does not explicitly state when not to use it or mention alternatives, leaving the usage guidance mostly implied.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

update_configA

Update Gopeed configuration (only provide fields to change).

Args: connections: HTTP concurrent connections (e.g. 16, 32). download_dir: Full path to download directory. proxy_enabled: Whether to enable proxy (True/False).

ParametersJSON Schema
NameRequiredDescriptionDefault
connectionsNo
download_dirNo
proxy_enabledNo

Output Schema

ParametersJSON Schema
NameRequiredDescription
resultYes

TDQS

A4.2/5.0
Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations, the description carries the behavioral burden. It discloses the important merge behavior (unmentioned fields are left unchanged), but does not address side effects, persistence, validation failures, or whether changes affect running downloads.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is compact and front-loaded: a one-sentence purpose followed by a clean Args list. Every line earns its place and there is no filler or repetition of schema types.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a simple tool with three optional scalar parameters and an output schema that can document the return value, this is nearly complete: purpose, merge behavior, and all parameter semantics are present. Minor gaps like error behavior or effect on existing tasks are not severe enough to drop below 4.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 0%, and the description compensates by explaining all three parameters: connections gets a semantic definition plus examples, download_dir requires a full path, and proxy_enabled maps to a boolean. It could add constraints or default/null handling, but it adds meaningful value beyond the raw schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb and resource ('Update Gopeed configuration') and adds the key partial-update qualifier 'only provide fields to change.' This clearly separates update_config from its read-only sibling get_config and from task-management siblings.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The opening sentence gives direct context: use this when you need to modify Gopeed configuration. The 'only provide fields to change' instruction also tells the agent how to scope arguments. It does not name alternatives explicitly, but get_config is naturally distinguished as the read counterpart and task tools operate on a different resource.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

  1. 10 tool updatesv0.3.1
    • First observedcreate_download_task
    • First observeddelete_completed_tasks
    • First observeddelete_done_tasks
    • First observeddelete_task
    • First observedget_config
    • First observedget_task_detail
    • First observedlist_tasks
    • First observedpause_task
    • First observedresume_task
    • First observedupdate_config

TDQS

B3.4/5.0

Scored across 10 tools

Disambiguation3/5

Most tools map clearly to distinct actions on distinct resources, such as create_download_task, pause_task, and get_config. However, delete_completed_tasks and delete_done_tasks are explicit duplicates, creating genuine ambiguity about which one to call.

Naming Consistency4/5

Tool names generally follow a consistent verb_noun pattern: create_download_task, list_tasks, pause_task, resume_task, update_config. The main inconsistency is the completed/done synonym pair and mixing list_ vs get_ for read operations.

Tool Count4/5

Ten tools is a reasonable size for a download-manager server, covering both task operations and configuration. The presence of a redundant alias makes the set slightly over-scoped, but it is not bloated.

Completeness4/5

The tool set covers the core download lifecycle well: create, list, get details, pause, resume, delete, and batch cleanup. Configuration get/update is also included. Minor gaps exist, such as no retry or task-editing operation, but these are not essential to the main workflow.

Maintenance

ActivityMaintained
ResponsivenessNo issues

Related MCP Connectors

Related MCP Servers