Activitywatch Server

TypeScript

MIT License

8bitgentleman

ActivityWatch MCP 服务器

一个 Model Context Protocol (MCP) 服务器，连接到 ActivityWatch，允许像 Claude 这样的大语言模型与你的时间跟踪数据进行交互。

功能

列出桶：查看所有可用的 ActivityWatch 桶
运行查询：执行强大的 AQL（ActivityWatch 查询语言）查询
获取原始事件：直接从任何桶中检索事件
获取设置：访问 ActivityWatch 配置设置

安装

你可以通过 npm 或自行构建来安装 ActivityWatch MCP 服务器。

从 npm 安装（即将推出）

bash 复制代码

# 全局安装
npm install -g activitywatch-mcp-server

# 或者本地安装
npm install activitywatch-mcp-server

从源代码构建

克隆此仓库：

bash 复制代码

git clone https://github.com/8bitgentleman/activitywatch-mcp-server.git
cd activitywatch-mcp-server

安装依赖项：
bash 复制代码
```
npm install
```
构建项目：
bash 复制代码
```
npm run build
```

前提条件

已安装并运行 ActivityWatch
Node.js（v14 或更高版本）
Claude for Desktop（或其他 MCP 客户端）

使用

与 Claude for Desktop 一起使用

打开你的 Claude for Desktop 配置文件：
- Windows: %APPDATA%\Claude\claude_desktop_config.json
- macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
添加 MCP 服务器配置：

json 复制代码

{
  "mcpServers": {
    "activitywatch": {
      "command": "activitywatch-mcp-server",
      "args": []
    }
  }
}

如果你是从源代码构建的，请使用：

json 复制代码

{
  "mcpServers": {
    "activitywatch": {
      "command": "node",
      "args": ["/path/to/activitywatch-mcp-server/dist/index.js"]
    }
  }
}

重启 Claude for Desktop
在 Claude 的界面中查找 MCP 图标以确认其正常工作

示例查询

以下是一些可以在 Claude 中尝试的示例查询：

列出所有桶："我有哪些 ActivityWatch 桶？"
获取应用程序使用情况摘要："你能告诉我今天我用得最多的应用程序是什么吗？"
查看浏览历史："我今天在哪些网站上花费了最多时间？"
检查生产力："我今天在生产力应用上花了多少时间？"
查看设置："我的 ActivityWatch 设置是什么？" 或 "你能检查 ActivityWatch 中的特定设置吗？"

可用工具

list-buckets

列出所有可用的 ActivityWatch 桶，并可选择按类型过滤。

参数：

type（可选）：按类型过滤桶（例如，"window", "web", "afk"）
includeData（可选）：在响应中包含桶数据

run-query

在 ActivityWatch 的查询语言（AQL）中运行查询。

参数：

timeperiods：要查询的时间段，格式为字符串数组。对于日期范围，使用格式：["2024-10-28/2024-10-29"]
query：在 ActivityWatch 查询语言中的查询语句数组，每个项目是一个完整的查询，语句之间用分号分隔
name（可选）：查询的名称（用于缓存）

重要：每个查询字符串应包含一个完整的查询，多个语句之间用分号分隔。

请求格式示例：

json 复制代码

{
  "timeperiods": ["2024-10-28/2024-10-29"],
  "query": ["events = query_bucket('aw-watcher-window_UNI-qUxy6XHnLkk'); RETURN = events;"]
}

注意：

timeperiods 应包含带有斜杠的预格式化日期范围
query 数组中的每个项目都是一个完整的查询，包含所有语句

get-events

从 ActivityWatch 桶中获取原始事件。

参数：

bucketId：要从中获取事件的桶 ID
start（可选）：开始日期/时间（ISO 格式）
end（可选）：结束日期/时间（ISO 格式）
limit（可选）：返回的最大事件数量

get-settings

从服务器获取 ActivityWatch 设置。

参数：

key（可选）：获取特定的设置键而不是所有设置

查询语言示例

ActivityWatch 使用简单的查询语言。以下是一些常见的模式：

复制代码

// 获取窗口事件
window_events = query_bucket(find_bucket("aw-watcher-window_"));
RETURN = window_events;

// 获取非 AFK 时的事件
afk_events = query_bucket(find_bucket("aw-watcher-afk_"));
not_afk = filter_keyvals(afk_events, "status", ["not-afk"]);
window_events = filter_period_intersect(window_events, not_afk);
RETURN = window_events;

// 按应用分组
window_events = query_bucket(find_bucket("aw-watcher-window_"));
events_by_app = merge_events_by_keys(window_events, ["app"]);
RETURN = sort_by_duration(events_by_app);

// 按应用名称过滤
window_events = query_bucket(find_bucket("aw-watcher-window_"));
code_events = filter_keyvals(window_events, "app", ["Code"]);
RETURN = code_events;

配置

服务器默认连接到 http://localhost:5600 上的 ActivityWatch API。如果您的 ActivityWatch 实例运行在不同的主机或端口上，您可以在源代码中修改这一点。

故障排除

ActivityWatch 未运行

如果 ActivityWatch 没有运行，服务器将显示连接错误。确保 ActivityWatch 正在运行并且可以通过 http://localhost:5600 访问。

查询错误

如果您遇到查询错误：

检查您的查询语法
确保桶 ID 是正确的
确认时间段内包含数据
查看 ActivityWatch 日志以获取更多详细信息

Claude/MCP 查询格式问题

如果 Claude 在通过此 MCP 服务器运行查询时报告错误，很可能是格式问题。确保您的查询遵循提示中的确切格式：

json 复制代码

{
  "timeperiods": ["2024-10-28/2024-10-29"],
  "query": ["events = query_bucket('aw-watcher-window_UNI-qUxy6XHnLkk'); RETURN = events;"]
}

常见问题：

时间段格式不正确（应为单个字符串内的 "start/end"）
查询语句被拆分成单独的数组元素而不是合并成一个字符串

最常见的格式问题

最常见的错误是 Claude 将每个查询语句拆分成自己的数组元素，如下所示：

json 复制代码

{
  "query": [
    "browser_events = query_bucket('aw-watcher-web');",
    "afk_events = query_bucket('aw-watcher-afk');",
    "RETURN = events;"
  ],
  "timeperiods": ["2024-10-28/2024-10-29"]
}

这是不正确的。相反，所有语句应该在一个字符串内：

json 复制代码

{
  "timeperiods": ["2024-10-28/2024-10-29"],
  "query": ["browser_events = query_bucket('aw-watcher-web'); afk_events = query_bucket('aw-watcher-afk'); RETURN = events;"]
}

向 Claude 提示

当提示 Claude 时，请非常明确地说明格式并使用示例。例如，说：

"运行一个查询，时间段为 ["2024-10-28/2024-10-29"]，查询为 ["statement1; statement2; RETURN = result;"]。重要：确保所有查询语句都在数组中的一个字符串内，而不是拆分成单独的数组元素。"

贡献

欢迎贡献！请随时提交 Pull Request。

许可证

MIT