项目简介

Issue Cards 是一个为AI编码助手和人工开发者设计的命令行议题追踪工具。它将项目议题和任务以结构化的Markdown文件形式存储在项目中，并提供一系列命令来管理这些议题。其核心特色是内置了一个Model Context Protocol (MCP) 服务器，以便AI助手能够直接访问和操作议题数据，获取任务上下文，并记录工作进展。

主要功能点

文件存储: 议题存储为项目内的Markdown文件，简单易管理。
任务序列: 任务列表按照清晰的顺序排列。
任务标签: 支持使用标签扩展任务，例如自动添加测试步骤。
丰富上下文: 展示每个任务所需的背景信息（问题、方法、指令等）。
Git集成: 自动暂存议题文件的更新。
AI集成 (MCP服务器): 提供标准化的API供AI助手调用，实现自动化议题管理。
AI友好输出: 命令输出格式规范，易于AI解析。

安装步骤

Issue Cards 是一个Node.js应用程序，可以通过npm进行安装：

# 全局安装 (推荐)
npm install -g issue-cards

# 或者使用npx (按需下载运行)
# npx issue-cards <command>

服务器配置

Issue Cards 的MCP服务器是为AI或LLM客户端（如Claude Code）提供服务的。客户端需要配置服务器的启动命令和参数来建立连接。典型的MCP客户端配置通常包含 'command' 和 'args' 字段。

以下是 Issue Cards MCP 服务器的两种常见启动方式，它们对应于MCP客户端配置中的 'command' 和 'args'：

使用全局安装版本:
- 'command': 'issue-cards-mcp-server'
- 'args': '[]' 或 '["--token", "你的密钥"]' (推荐用于身份验证)
使用npx (无需全局安装):
- 'command': 'npx'
- 'args': '["issue-cards-mcp-server@latest"]' 或 '["issue-cards-mcp-server@latest", "--token", "你的密钥"]' (推荐用于身份验证)

重要提示:

MCP客户端的配置格式依赖于客户端本身，但通常会包含 'command' 字段指定启动服务器的程序路径（例如 'issue-cards-mcp-server' 或 'npx'），以及 'args' 字段指定传递给该程序的参数（例如 '["--token", "你的密钥"]'）。
'--token <your-secret-token>' 参数用于启用简单的基于Token的身份验证。在生产环境或需要安全访问的场景中强烈建议使用。请将 '<your-secret-token>' 替换为你自己生成的强密码或密钥。

基本使用方法

在项目目录中初始化议题追踪：

issue-cards init

创建一个新的议题（例如功能需求）：

issue-cards create feature --title "添加用户登录功能" --problem "用户需要安全登录" --task "创建用户模型" --task "实现登录接口"

查看当前需要处理的任务及其上下文：

issue-cards current

完成当前任务并自动切换到下一个：

issue-cards complete-task

列出所有开放的议题：

issue-cards list

显示特定议题的详细内容：

issue-cards show 0001

添加一个新任务到当前议题或指定议题：

issue-cards add-task "编写单元测试"
issue-cards add-task "编写API文档" --issue 0001

添加笔记、问题或记录失败尝试到当前议题：

issue-cards add-note "思考使用JWT进行认证" --section "Planned approach"
issue-cards add-question "如何处理密码重置？"
issue-cards log-failure "尝试了基于Session的认证" --reason "不易扩展"

查看可用的议题或任务标签模板：

issue-cards templates
issue-cards templates --type tag
issue-cards templates --type tag --name unit-test

关键词

信息