使用说明

Calq MCP

用于时间跟踪、项目管理、人工智能驱动的内存和团队协作的模型上下文协议（MCP）服务器。

特性

⏱️ 时间跟踪

定时器系统 -用于实时跟踪的启动/停止计时器
手动记录 -使用回溯支持记录时间
计费 -将条目标记为可计费/已计费，跟踪未计费时间

🧠 AI驱动的内存

语义搜索 -按意义查找记忆和条目，而不仅仅是关键字
个人&共享 -将笔记保密或与团队共享
项目/客户链接 -将记忆与特定项目或客户联系起来
矢量存储器 -技术支持： ChromaDB 和 Voyage AI 嵌入

👥 团队协作

GitHub OAuth -通过GitHub对团队成员进行身份验证（集成到MCP流中）
基于角色的访问 -管理员和成员角色
每用户数据 -计时器和条目是用户范围的

📊 项目和客户管理

客户 -管理客户信息
项目 -以小时费率将项目与客户联系起来
发票摘要 -获取按客户端和计算值分组的未开票时间

先决条件

Node.js 20+
PostgreSQL -结构化数据的关系数据库
ChromaDB -用于语义搜索的矢量数据库
Voyage AI API键 -用于生成嵌入
GitHub OAuth应用程序 -用于用户身份验证

安装

选项1:Docker Compose（推荐）

这会自动设置Calq、PostgreSQL和ChromaDB：

git clone https://github.com/Calq-dev/calq-mcp.git
cd calq-mcp

# Copy and configure environment
cp .env.example .env
# Edit .env with your API keys

# Start services (uses default ports 3000 and 8000)
docker compose up -d

# Or with custom ports
MCP_PORT=3001 CHROMA_PORT=8001 docker compose up -d

服务：

Calq MCP: http://localhost:${MCP_PORT}/mcp （默认值：3000）
PostgreSQL：Docker内部（端口5432）
ChromaDB: http://localhost:${CHROMA_PORT} （默认值：8000，Docker内部）

方案2：地方发展

# 1. Start PostgreSQL and ChromaDB (required)
docker run -d --name postgres -p 5432:5432 \
  -e POSTGRES_USER=calq -e POSTGRES_PASSWORD=calq -e POSTGRES_DB=calq \
  postgres:16-alpine

docker run -d --name chromadb -p 8000:8000 chromadb/chroma:latest

# 2. Clone and install
git clone https://github.com/Calq-dev/calq-mcp.git
cd calq-mcp
npm install

# 3. Configure environment
cp .env.example .env
# Edit .env with your API keys

# 4. Push database schema
npm run db:push

# 5. Start the server
node src/index.js

配置

环境变量

变量	必填	描述
`DATABASE_URL`	是	PostgreSQL连接URL
`POSTGRES_PASSWORD`	否	Docker的PostgreSQL密码（默认：calq）
`VOYAGE_API_KEY`	是	Voyage AI API嵌入密钥
`CHROMA_URL`	否	ChromaDB URL（默认值： `http://localhost:8000`)
`GITHUB_CLIENT_ID`	是	GitHub OAuth应用程序客户端ID
`GITHUB_CLIENT_SECRET`	是	GitHub OAuth应用程序客户端机密
`MCP_PORT`	无	服务器端口（默认值：3000）
`OAUTH_CALLBACK_URL`	否	OAuth回调（默认值： `http://localhost:3000/oauth/callback`)

数据库管理

Calq使用淋ORM 使用PostgreSQL：

# Generate migrations from schema changes
npm run db:generate

# Apply migrations
npm run db:migrate

# Push schema directly (development)
npm run db:push

# Open Drizzle Studio
npm run db:studio

GitHub OAuth设置

首选 GitHub开发人员设置
点击“新建OAuth应用程序”
填写：
- 应用程序名称： 简洁计算器
- 主页网址： http://localhost:3000
- 授权回调URL: http://localhost:3000/oauth/github/callback
复制客户端ID并生成客户端密钥
将两者都添加到您的 .env 文件

Claude桌面配置

添加到您的Claude桌面配置(~/Library/Application Support/Claude/claude_desktop_config.json 在macOS上）：

{
  "mcpServers": {
    "calq": {
      "url": "http://localhost:3000/mcp"
    }
  }
}

当你第一次使用Calq时，Claude Desktop会打开一个浏览器进行GitHub身份验证。

工具

时间跟踪

工具	说明
`commit`	记录时间，包括消息、项目和可选日期
`start`	为项目启动计时器
`stop`	停止计时器并记录时间
`timer_status`	检查计时器是否正在运行
`cancel_timer`	丢弃计时器而不记录
`delete`	删除时间条目
`edit`	修改现有条目

摘要

工具	说明
`list_projects`	列出所有项目的总时间
`list_projects_detailed`	包含客户信息和价值观的项目
`get_project_summary`	项目的详细摘要
`get_today_summary`	按项目划分的今天时间
`get_weekly_summary`	本周每天的时间
`get_unbilled`	未开票时间汇总
`get_invoice_summary`	客户提供的有价值的未计费时间

记忆

工具	说明
`remember`	存储内存（个人/共享，链接到项目/客户端）
`idea`	快速捕捉想法
`recall`	语义搜索记忆
`search_entries`	语义搜索时间条目
`list_memories`	列出所有回忆
`list_ideas`	列出所有捕获的想法
`forget`	删除内存

客户与项目

工具	说明
`add_client`	添加新客户端
`list_clients`	列出所有客户
`configure_project`	使用客户和小时费率创建/更新项目

用户

工具	说明
`whoami`	显示当前用户信息
`list_users`	列出所有用户（仅限管理员）
`set_user_role`	更改用户角色（仅限管理员）
`team_summary`	团队活动总结

使用示例

"Start timing the website project"
"Stop - finished the navbar"
"Log 2 hours to API work yesterday: implemented auth"
"Remember: client wants deadline moved to January"
"Recall: what did the client say about deadlines?"
"What's my unbilled time for Acme Corp?"
"Configure project website with client Acme and rate 95"

建筑

┌─────────────────┐     ┌─────────────────┐     ┌─────────────────┐
│  Claude Desktop │────▶│   Calq MCP      │────▶│    ChromaDB     │
│                 │     │  (Port 3000)    │     │  (Port 8000)    │
└─────────────────┘     └────────┬────────┘     └─────────────────┘
                                 │
                                 ▼
                        ┌─────────────────┐
                        │   PostgreSQL    │
                        │  (Port 5432)    │
                        └─────────────────┘

PostgreSQL -结构化数据的真实来源（条目、项目、用户）
ChromaDB -用于语义搜索的矢量存储（记忆、条目嵌入）
淋ORM -类型安全数据库访问层

数据存储

在Docker中，数据通过卷持久化：

calq-data -应用程序数据
postgres-data -PostgreSQL数据库
chroma-data -ChromaDB嵌入

许可证

麻省理工学院