Calq MCP

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

配置

环境变量

数据库管理

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设置

1. 首选
2. 点击“新建OAuth应用程序”
3. 填写：

- 应用程序名称： 简洁计算器 - 主页网址： http://localhost:3000 - 授权回调URL: http://localhost:3000/oauth/github/callback

1. 复制客户端ID并生成客户端密钥
2. 将两者都添加到您的 .env 文件

Claude桌面配置

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

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

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

工具

时间跟踪

摘要

记忆

客户与项目

用户

使用示例

"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嵌入

许可证

麻省理工学院