AI导哈

项目工单管理服务器

一个MCP服务器，为Claude Code提供对CodebaseHQ（项目管理和工单平台）的访问权限，支持从Claude Code或任何MCP兼容客户端读取、搜索、创建和更新工单。

  • by bdteo
  • JavaScript
  • 本地部署
  • 1 星标
  • 更新于
在 GitHub 查看 bdteo/CodebaseHQ

使用说明

CodebaseHQ MCP服务器

MCP（模型上下文协议）服务器，提供 克劳德代码 访问 CodebaseHQ --项目管理和票务平台。直接从Claude Code或任何兼容MCP的客户端读取、搜索、创建和更新票证。

特性

  • 列出项目 --浏览CodebaseHQ帐户中的所有项目
  • 搜索门票 --带分页的完整查询语法（状态、受让人、优先级、类型等）
  • 查看门票详情 --获取包含状态/优先级ID的完整工单信息以进行更新
  • 阅读评论 --包含作者姓名和文件附件的完整对话线程
  • 活动动态 --查看最近的项目活动（谁创建/更新了什么）
  • 列出团队成员 --发现要分配的用户ID
  • 创建工单 --创建具有类型、优先级和受让人的新票证
  • 更新门票 --添加注释、更改状态/优先级/受让人、重命名票证

先决条件

设置

1.获取您的API证书

首选 CodebaseHQ→ 设置→ 我的资料 并注意：

  • API用户名 --格式： account/username （例如。 mycompany/john)
  • API密钥 --40个字符串

2.设置环境变量

添加到shell配置中（例如。 ~/.zshrc, ~/.bashrc):

export CODEBASEHQ_ACCOUNT="your-account"       # the part before /
export CODEBASEHQ_USERNAME="your-username"      # the part after /
export CODEBASEHQ_API_KEY="your-api-key"
export CODEBASEHQ_DEFAULT_PROJECT="my-project"  # optional — skip the project param in every tool call

3.克隆和构建

git clone https://github.com/bdteo/CodebaseHQ.git
cd CodebaseHQ
pnpm install
pnpm run build

4.用克劳德代码注册

挑选 一 下面的方法。

选项A:CLI命令（全局）

claude mcp add codebasehq -- node /absolute/path/to/CodebaseHQ/dist/index.js

服务器从shell继承环境变量，因此 CODEBASEHQ_* 您在步骤2中设置的变量将被自动拾取。

选项B：全局配置文件

添加 ~/.claude.json:

{
  "mcpServers": {
    "codebasehq": {
      "command": "node",
      "args": ["/absolute/path/to/CodebaseHQ/dist/index.js"]
    }
  }
}

选项C：项目范围配置

创建一个 .mcp.json 在项目根目录中（有助于与团队共享）：

{
  "mcpServers": {
    "codebasehq": {
      "command": "node",
      "args": ["/absolute/path/to/CodebaseHQ/dist/index.js"],
      "env": {
        "CODEBASEHQ_ACCOUNT": "${CODEBASEHQ_ACCOUNT}",
        "CODEBASEHQ_USERNAME": "${CODEBASEHQ_USERNAME}",
        "CODEBASEHQ_API_KEY": "${CODEBASEHQ_API_KEY}",
        "CODEBASEHQ_DEFAULT_PROJECT": "${CODEBASEHQ_DEFAULT_PROJECT}"
      }
    }
  }
}

这 ${VAR} 语法引用shell环境变量——文件中没有秘密。

5.验证

重新启动Claude Code，然后问：

“列出我的CodebaseHQ项目”

如果服务器连接，您将看到您的项目。如果没有，请检查 故障排除.

工具

工具 类型 描述
list_projects 阅读 列出所有有票计数的项目
search_tickets 阅读 使用查询语法和分页搜索/列出门票
get_ticket 读取 按ID列出的完整工单详细信息（包括用于更新的字段ID）
get_ticket_notes 阅读 评论、更改历史记录和附件
get_activity 阅读 最近的项目活动提要
list_users 阅读 具有分配ID的团队成员
create_ticket 写 创建新票
update_ticket 写 添加评论和/或更改状态、优先级、受让人

搜索查询语法

这 search_tickets 该工具支持CodebaseHQ的查询语法：

status:open                    # by status
assignee:me                    # your tickets
priority:high                  # by priority
type:bug                       # Bug, Feature, or Task
category:General               # by category
sort:updated order:desc        # sorting
not-status:closed              # negation
assignee:me status:open        # combine filters

用法示例

问克劳德这样的问题：

  • “给我看所有未结的票”
  • “分配给我的票是什么？”
  • “给我看23号票及其评论”
  • “这个项目最近发生了什么？”
  • “为登录页面问题创建错误单”
  • “将票#5标记为已关闭，并添加评论”
  • “谁在队里？把10号票给马里奥”

建筑

src/
├── index.ts            # MCP server, tool definitions, request handlers
├── codebasehq-api.ts   # HTTP client (JSON responses, XML write bodies, rate limiting)
└── types.ts            # TypeScript types for API responses
  • 运输： stdio（标准输入/标准输出）
  • API CodebaseHQ REST API v3(api3.codebasehq.com)
  • 认证： HTTP基本(account/username:api_key)
  • 响应： JSON（读）、XML（写体）
  • 速率限制： 429上自动重试并回退
  • 运行时依赖关系： @modelcontextprotocol/sdk 仅

故障排除

“CodebaseHQ凭据无效或网络错误”

  • 仔细检查你的 CODEBASEHQ_ACCOUNT, CODEBASEHQ_USERNAME，以及 CODEBASEHQ_API_KEY 价值观
  • 帐户/用户名来自于在上拆分API用户名 /
  • 在CodebaseHQ中验证您的API密钥→ 设置→ 我的资料

克劳德代码中未显示服务器

  • 跑 claude mcp list 检查连接状态
  • 确保路径 dist/index.js 是绝对的
  • 重建与 pnpm run build 任何源更改后
  • 配置更改后重新启动Claude代码

速率限制

  • 服务器在延迟后自动重试
  • 减少 limit 如果频繁达到限制，则查询中的参数

免责声明

这个项目是 不隶属于、不受认可或与之相关 aTech媒体有限公司/Krystal主机有限公司（CodebaseHQ的制造商）。它是一个独立的开源API客户端。您需要自己的CodebaseHQ帐户和API凭据才能使用它。

许可证

麻省理工学院

相关 MCP