活动监视MCP服务器
连接到的模型上下文协议（MCP）服务器 活动观察，允许像Claude这样的LLM与您的时间跟踪数据进行交互。
特性
- 列出Buckets：查看所有可用的ActivityWatch bucket
- 运行查询：执行强大的AQL（ActivityWatch查询语言）查询
- 获取原始事件：直接从任何存储桶中检索事件
- 获取设置：访问ActivityWatch配置设置
安装
您可以从npm或自己构建来安装ActivityWatch MCP服务器。
从npm安装（即将推出）
# Global installation
npm install -g activitywatch-mcp-server
# Or install locally
npm install activitywatch-mcp-server从源头构建
- 克隆此存储库：
git clone https://github.com/8bitgentleman/activitywatch-mcp-server.git
cd activitywatch-mcp-server- 安装依赖项：
npm install- 构建项目：
npm run build先决条件
- 活动观察 已安装并正在运行
- Node.js（v14或更高版本）
- Claude for Desktop（或任何其他MCP客户端）
用法
使用Claude for Desktop
- 打开Claude for Desktop配置文件：
- 窗户： %APPDATA%\Claude\claude_desktop_config.json - macOS： ~/Library/Application Support/Claude/claude_desktop_config.json
- 添加MCP服务器配置：
{
"mcpServers": {
"activitywatch": {
"command": "activitywatch-mcp-server",
"args": []
}
}
}如果您是从源代码构建的，请使用：
{
"mcpServers": {
"activitywatch": {
"command": "node",
"args": ["/path/to/activitywatch-mcp-server/dist/index.js"]
}
}
}- 重新启动桌面版的Claude
- 在Claude的界面中查找MCP图标，以确认其正常工作
查询示例
以下是您可以在Claude中尝试的一些示例查询：
- 列出你的所有水桶：“我有什么ActivityWatch桶？”
- 获取应用程序使用情况摘要：“你能给我看看我今天用得最多的应用程序吗？”
- 查看浏览历史记录：“我今天花在哪些网站上的时间最多？”
- 检查生产率：“我今天在生产力应用程序上花了多少时间？”
- 视图设置：“我的ActivityWatch设置是什么？”或“您能在ActivityWatch中检查特定设置吗？”
可用工具
列出bucket
列出所有可用的ActivityWatch bucket，并提供可选的类型筛选。
参数：
type（可选）：按类型过滤桶（例如，“窗口”、“网络”、“afk”）includeData（可选）：在响应中包含存储桶数据
运行查询
使用ActivityWatch的查询语言（AQL）运行查询。
参数：
timeperiods：查询格式化为字符串数组的时间段。对于日期范围，请使用格式：["2024-10-28/2024-10-29"]query：ActivityWatch查询语言中的查询语句数组，其中每个项都是一个完整的查询，语句之间用分号分隔name（可选）：查询的名称（用于缓存）
重要：每个查询字符串应包含一个完整的查询，其中包含多个用分号分隔的语句。
请求格式示例：
{
"timeperiods": ["2024-10-28/2024-10-29"],
"query": ["events = query_bucket('aw-watcher-window_UNI-qUxy6XHnLkk'); RETURN = events;"]
}请注意：
timeperiods应具有带斜线的预格式化日期范围- 中的每个项目
query数组是一个包含所有语句的完整查询
获取事件
从ActivityWatch存储桶中获取原始事件。
参数：
bucketId：从中获取事件的bucket的IDstart（可选）：ISO格式的开始日期/时间end（可选）：ISO格式的结束日期/时间limit（可选）：要返回的最大事件数
获取设置
从服务器获取ActivityWatch设置。
参数：
key（可选）：获取特定设置键，而不是所有设置
查询语言示例
ActivityWatch使用简单的查询语言。以下是一些常见的模式：
// Get window events
window_events = query_bucket(find_bucket("aw-watcher-window_"));
RETURN = window_events;
// Get only when not 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;
// Group by app
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);
// Filter by app name
window_events = query_bucket(find_bucket("aw-watcher-window_"));
code_events = filter_keyvals(window_events, "app", ["Code"]);
RETURN = code_events;配置
服务器连接到位于的ActivityWatch API http://localhost:5600 默认情况下。如果您的ActivityWatch实例正在其他主机或端口上运行，您可以在源代码中进行修改。
故障排除
活动观察未运行
如果ActivityWatch未运行，服务器将显示连接错误。确保ActivityWatch正在运行，并且可以在以下位置访问http://localhost:5600.
查询错误
如果您遇到查询错误：
- 检查查询语法
- 确保存储桶ID正确
- 验证时间段是否包含数据
- 查看ActivityWatch日志以了解更多详细信息
Claude/MCP查询格式问题
如果Claude在通过此MCP服务器运行查询时报告错误，则可能是由于格式问题。确保您的查询在提示中遵循以下确切格式：
{
"timeperiods": ["2024-10-28/2024-10-29"],
"query": ["events = query_bucket('aw-watcher-window_UNI-qUxy6XHnLkk'); RETURN = events;"]
}常见问题：
- 时间段格式不正确（应为数组中单个字符串的“开始/结束”）
- 查询语句拆分为单独的数组元素，而不是组合在一个字符串中
最常见的格式问题
最常见的错误是Claude将每个查询语句拆分为自己的数组元素，如下所示：
{
"query": [
"browser_events = query_bucket('aw-watcher-web');",
"afk_events = query_bucket('aw-watcher-afk');",
"RETURN = events;"
],
"timeperiods": ["2024-10-28/2024-10-29"]
}这是不正确的。相反，所有语句都应该在数组中的一个字符串中：
{
"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时，要非常明确地说明格式并使用示例。例如，假设：
“按以下方式运行包含时间段的查询 ["2024-10-28/2024-10-29"] 并查询为 ["statement1; statement2; RETURN = result;"]重要提示：确保所有查询语句都在数组中的单个字符串中，而不是拆分为单独的数组元素。"
贡献
欢迎投稿！请随时提交拉取请求。