Amazon Q History MCP Server

Amazon Q历史MCP服务器

跟踪亚马逊Q会话，维护崩溃的上下文，并监控目标的进展。

特性

• 会话跟踪：具有代理名称和时间戳的唯一会话ID
• 会话管理：优雅地关闭并在多个会话之间切换
• 上下文保护：提取并存储目标、要求和约束
• 进度监控：跟踪行动和成功标准
• 故障恢复：备份到 /tmp 具有恢复能力
• 工作日志管理：按时间顺序跟踪行动和状态
• 备份还原：从以下位置还原已删除的会话 /tmp 备份
• 挂钩集成：支持Q CLI挂钩事件，用于自动操作跟踪

安装

cd /home/jmrmedev/mcp-servers/amazon-q-history
npm install

配置

存储模式

创建 .amazon-q-history/config.json 在项目根目录中配置存储行为。

服务器模式（默认）

{
  "storage_mode": "server"
}

• 存储在MCP服务器目录中的历史记录
• 备份在 /tmp/amazon-q-history/
• 无删除保护

项目模式

{
  "storage_mode": "project",
  "session_ttl_hours": 24,
  "prefer_recent_session": true,
  "restore_latest": true,
  "allowed_paths": [
    "/home/user/repos/project1",
    "/home/user/repos/project2"
  ]
}

• 历史记录存储在 .amazon-q-history/ 目录
• restore_latest：启动时自动还原最近的会话
• 也在项目目录中备份
• 已启用删除保护
• 历史与项目同在
• 会话\_ ttl小时数：在此时间内重复使用会话

- 24 （默认）-会话在24小时后过期 - 0 或 null -无限TTL，永不过期（始终重用旧会话） - 省略字段-无限TTL（无过期）

• prefer_recent_session：当同一代理存在多个会话时（默认值： true)

- true -始终选择最近的会话（如加载游戏中的最新保存） - false -选择第一个匹配会话（旧行为）

• 允许路径：工作区/多项目设置的其他路径（自动检测 .code-workspace 文件）

- 支持绝对路径： /home/user/repos/project1 - 支持相对路径： ../, ../sibling-project, ../../parent - 从项目目录解析的相对路径

工具权限

控制项目中可用的工具。

全部允许（默认）

{
  "tools": {
    "mode": "all"
  }
}

所有工具都可用，没有限制。

白名单模式

{
  "tools": {
    "mode": "allow",
    "list": [
      "track_session",
      "log_prompt",
      "log_action",
      "get_recent_context"
    ]
  }
}

只有列出的工具可用。限制性最强。

黑名单模式

{
  "tools": {
    "mode": "deny",
    "list": [
      "clear_session_history",
      "restore_backup"
    ]
  }
}

除列出的工具外，所有可用工具。有利于阻止危险操作。

预设配置

复制预设配置以快速开始：

# Modern development with auto-restore (recommended)
cp preset-configs/modern-dev.json .amazon-q-history/config.json

# Auto-restore latest session on startup
cp preset-configs/auto-restore.json .amazon-q-history/config.json

# Read-only access (viewing only)
cp preset-configs/read-only.json .amazon-q-history/config.json

# Safe development (no destructive operations)
cp preset-configs/safe-dev.json .amazon-q-history/config.json

# Long-term projects (infinite TTL, never expires)
cp preset-configs/long-term.json .amazon-q-history/config.json

# Workspace/multi-project setup (supports relative paths)
cp preset-configs/workspace.json .amazon-q-history/config.json

# Git-focused workflow
cp preset-configs/git-workflow.json .amazon-q-history/config.json

# Team-safe (prevent accidental deletes)
cp preset-configs/team-safe.json .amazon-q-history/config.json

# Project storage (default permissions)
cp preset-configs/project-storage.json .amazon-q-history/config.json

# Server storage (default permissions)
cp preset-configs/server-storage.json .amazon-q-history/config.json

预置模式

只读.json

• 存储：项目模式
• 工具：仅查看工具（get_session_history、get_cent_context、check_progress）
• 用例：在不进行更改的情况下查看历史记录

safe-dev.json

• 存储：项目模式
• 工具：除clear_session_history和restore_backup之外的所有工具
• 用例：防止意外删除的开发

long term.json

• 存储：项目模式
• TTL:0（无限，永不过期）
• 工具：核心工具+列表_会话
• 用例：您在数周/数月后返回的长期项目

workspace.json

• 存储：项目模式
• 允许的路径：支持相对路径(., ../, ../project)
• 工具：核心工具+列表_会话
• 用例：具有兄弟目录的多项目工作区

git-workflow.json

• 存储：项目模式
• 工具：会话跟踪、git集成和查看工具
• 用例：以Git为中心的开发工作流程

team-safe.json

• 存储：项目模式
• 工具：除clear_session_history之外的所有工具
• 用例：应保存历史的团队环境

project-storage.json

• 存储：项目模式
• 工具：全部可用
• 用例：功能齐全的基于项目的存储

server-storage.json

• 存储：服务器模式
• 工具：全部可用
• 用例：默认集中式存储

在项目中设置config.json

分步指南

1.创建配置目录

cd /path/to/your/project
mkdir -p .amazon-q-history

2.选择您的配置方法

选项A：使用预设（推荐）

# Copy a preset that matches your needs
cp /path/to/amazon-q-history/preset-configs/safe-dev.json .amazon-q-history/config.json

选项B：创建自定义配置

# Create config.json manually
cat > .amazon-q-history/config.json > .gitignore
echo ".amazon-q-history/backup/" >> .gitignore
echo ".amazon-q-history/logs/" >> .gitignore

选项2：保持配置本地

# Ignore entire .amazon-q-history directory
echo ".amazon-q-history/" >> .gitignore

故障排除

配置未加载？

• 确保文件命名准确 config.json
• 检查文件是否在 .amazon-q-history/ 项目根目录
• 验证JSON语法是否有效： cat .amazon-q-history/config.json | jq

工具意外堵塞？

• 检查 tools.mode 设置
• 验证工具名称是否在正确列表中（允许与拒绝）
• 查看文档中的可用工具

存储路径问题？

• 确认 storage_mode 是“服务器”还是“项目”
• 检查目录权限
• 验证 .amazon-q-history/ 目录存在

可用工具参考

所有可以通过配置控制的工具：

• track_session -初始化会话
• init_presession -浏览会话而不创建会话
• log_prompt -记录提示
• log_action -手动记录
• log_git_commits -Git集成
• get_session_history -查看历史记录
• get_recent_context -最近的背景
• check_progress -进度监控
• mark_criteria_complete -标记目标完成
• clear_session_history -删除历史记录
• restore_backup -还原会话
• restore_latest -自动还原最近的会话
• init_project_storage -初始化项目模式
• process_hook -吊钩加工
• list_sessions -列出所有会话
• close_session -优雅地结束当前会议
• switch_session -切换到其他会话

用法

会话管理

# Browse sessions without creating one (presession mode)
init_presession

# Automatically restore the most recent session (recommended)
restore_latest

# Close current session gracefully
close_session

# List all available sessions
list_sessions

# Switch to a different session
switch_session --session_id "2025-12-09T15-30-45_kiro-cli_abc123"

看 会话管理文档 查看详细的工作流程和示例。

初始化会话

# Start tracking for current directory
track_session --agent_name "amazon-q-developer"

记录用户提示

# Log prompt and extract goals/requirements
log_prompt --prompt "I want to create a React app with authentication. It should use JWT tokens and have a login page."

手动操作日志

# Log Q actions manually (recommended for precise control)
log_action --action "Created React app structure" --files_changed "['src/App.js', 'package.json']" --status "success"

Git集成（可选）

# Import recent git commits into worklog
log_git_commits --max_commits 5

# Import commits from last hour
log_git_commits --since "1 hour ago"

# Import from specific branch
log_git_commits --branch "feature/auth" --max_commits 10

基于钩子的操作跟踪

# Process Q CLI hook events for precise operation tracking (advanced)
process_hook --hook_event_name "preToolUse" --tool_name "fs_read" --tool_input {...}
process_hook --hook_event_name "postToolUse" --tool_name "fs_read" --tool_input {...} --tool_response {...}
process_hook --hook_event_name "stop"

检查进度

# See current progress and session data
check_progress
get_session_history

# Get recent context without overwhelming Q (recommended for large sessions)
get_recent_context

# Get more context if needed (incremental approach)
get_recent_context --prompt_count 10 --action_count 20

从备份中恢复

# List all available sessions (active and backup)
list_sessions

# Or use restore_backup without parameters
restore_backup

# Example output:
# **Active Sessions:**
# - 2025-10-13T19-04-26_amazon-q-developer_384fc4e1
#   Agent: amazon-q-developer, Created: 2025-10-13
#
# **Backup Sessions (deleted from active):**
# - 2025-10-13T19-09-26_amazon-q-developer_fbd33373
#   Agent: amazon-q-developer, Created: 2025-10-13

# Resume an active session (no restore needed)
track_session --agent_name "amazon-q-developer"

# Restore a backup session (deleted from active)
restore_backup --session_id "2025-10-13T19-04-26_amazon-q-developer_384fc4e1"

清除历史记录

# Clear session history with confirmation
clear_session_history --confirm true

整套工具

核心会话管理

• track_session -初始化/恢复会话
• log_prompt -使用上下文提取记录提示
• get_session_history -使用摘要检索会话数据
• get_recent_context -获取最近的提示/操作（大型会话的上下文安全）
• check_progress -监控目标完成情况
• clear_session_history -清理并确认
• list_sessions -列出所有会话（活动和备份）
• restore_backup -从备份中恢复或恢复活动会话

运营跟踪

• log_action -手动操作日志记录（推荐）
• log_git_commits -导入git提交历史记录（可选）
• process_hook -Q CLI钩子事件处理（高级）

进度管理

• mark_criteria_complete -手动将成功标准标记为完成

恢复和备份

• 自动备份到 /tmp/amazon-q-history/
• 会话摘要，便于识别
• 完整的崩溃恢复功能

上下文管理

避免上下文溢出

包含数千个动作的大型会话可能会淹没Q的上下文窗口。使用 get_recent_context 为了实现安全的上下文检索：

# Default: Last 5 prompts + 10 actions (recommended)
get_recent_context

# Need more context? Increase incrementally
get_recent_context --prompt_count 8 --action_count 15

# For detailed investigation (use carefully)
get_recent_context --prompt_count 15 --action_count 30

语境策略

• 从小事做起：使用默认的5个提示+10个操作
• 逐步扩大：仅在需要更多上下文时才增加计数
• 自下而上的阅读：总是先获取最新条目
• 固定尺寸：永远不会超过指定的限制

何时使用每种工具

• get_recent_context - 推荐 用于积极工作和大型会议
• get_session_history -仅提供基本会话统计数据和摘要
• check_progress -目标完成状态

文件结构

storage/sessions/2024-10-13T13-01-17_amazon-q-developer_abc12345/
├── metadata.json          # Session info and configuration
├── history.json           # User prompts and session events (context resets)
├── goals.json            # Extracted goals and requirements
├── success-criteria.json # Generated success criteria
└── worklog.json          # Detailed action tracking and file changes

备份位置

所有文件都会自动备份到 /tmp/amazon-q-history/ 为了恢复。

会话ID格式

YYYY-MM-DDTHH-MM-SS_agent-name_hash

例子： 2024-10-13T13-01-17_amazon-q-developer_abc12345

预设代理配置

即用型代理配置，集成Amazon Q History和自动会话跟踪。

可用预设

basic-dev-agent.json

• 目的：一般开发工作
• 特性：会话跟踪，自动提示日志记录
• MCP服务器：仅亚马逊Q历史
• 最适合：简单的开发任务、学习、实验

使用说明

1.复制预设配置

从可用的预设代理中选择：

• basic-dev-agent.json -具有现代会话管理的简单开发代理
• modern-dev-agent.json -具有自动还原和git集成的高级代理
• git-tracking-agent.json -专门用于git工作流跟踪

# Copy modern preset (recommended)
cp /home/jmrmedev/mcp-servers/amazon-q-history/preset-agents/modern-dev-agent.json ~/.aws/amazonq/cli-agents/

# Or copy basic preset
cp /home/jmrmedev/mcp-servers/amazon-q-history/preset-agents/basic-dev-agent.json ~/.aws/amazonq/cli-agents/

# Or copy to project-specific location
cp /home/jmrmedev/mcp-servers/amazon-q-history/preset-agents/modern-dev-agent.json /path/to/project/.amazonq/cli-agents/

2.自定义配置

编辑复制的文件以进行调整：

• 当前工作目录：设置到您的项目目录
• 代理名称：更新以匹配您的用例
• MCP服务器路径：验证路径是否适用于您的系统
• 附加工具：根据需要添加特定于项目的工具

3.开始使用

# Use the agent
q chat --agent your-agent-name

# The agent will automatically:
# - Initialize session tracking
# - Enable auto-tracking of operations
# - Log all prompts and tool usage
# - Maintain context across Q restarts

自动功能

预设代理包括：

会话管理

• 自动初始化：会话跟踪自动启动
• 上下文保存：在对话中保持目标和进展
• 崩溃恢复：会话已备份到 /tmp/amazon-q-history/

挂钩集成

• 用户提示：：使用上下文提取记录每个用户提示
• 代理商说明：使用echo命令指示代理行为
• 会话清理：通过代理指令处理会话管理

进度跟踪

• 目标提取：根据用户提示自动识别目标
• 成功标准：生成可衡量的完成标准
• 进度监控：跟踪行动和完成状态

定制提示

添加更多MCP服务器

"mcpServers": {
    "your-server": {
        "type": "stdio",
        "command": "node",
        "args": ["/path/to/your/server.js"],
        "timeout": 120000,
        "disabled": false
    }
}

添加自定义挂钩说明

"hooks": {
    "userPromptSubmit": [
        {
            "command": "echo 'Custom instruction for agent behavior'"
        }
    ],
    "agentSpawn": [
        {
            "command": "echo 'IMPORTANT: Use track_session at session start. Optionally use log_git_commits to import commit history.'"
        }
    ]
}

工具限制

"toolsSettings": {
    "fs_write": {
        "allowedPaths": ["./**/*.js", "./**/*.json"],
        "deniedPaths": ["./**/.env*"]
    }
}

故障排除

钩子错误

如果您看到“找不到命令”错误：

• 确保Amazon Q History MCP服务器正在运行
• 检查 cwd 在代理配置中设置正确
• 验证MCP服务器路径是否可访问
• 记住：钩子使用shell命令，而不是直接使用MCP工具

缺少会话文件

更新后的服务器确保所有文件（goals.json、history.json等）都是一致创建的。如果文件丢失：

• 重新启动代理以触发文件初始化
• 检查 /tmp/amazon-q-history/ 用于备份副本
• 使用 restore_backup 用于恢复会话的工具

上下文溢出

当Q的上下文在对话中重置时：

• 同一会话继续（未创建新会话）
• 上下文重置已记录在会话历史记录中
• 保留所有先前的目标和进展

Git集成

这 log_git_commits 该工具允许您将git提交历史导入会话工作日志。这是一个与手动配合使用的可选功能 log_action 登录中。

用法

# Import last 5 commits
log_git_commits --max_commits 5

# Import commits from last hour
log_git_commits --since "1 hour ago"

# Import commits from last day
log_git_commits --since "24 hours ago" --max_commits 20

# Import from specific branch
log_git_commits --branch "feature/auth" --max_commits 10

进口什么

每次提交都会被记录为一个操作，其中包括：

• 行动：“Git提交：｛提交消息｝”
• 更改的文件：提交中修改的文件列表
• 时间戳：提交日期/时间
• 元数据:

- git_hash：提交SHA - author：提交作者 - source：“git”

工作日志条目示例

{
  "action": "Git commit: Add user authentication",
  "files_changed": ["src/auth.js", "src/middleware/auth.js"],
  "status": "success",
  "timestamp": "2025-12-05T19:30:00Z",
  "metadata": {
    "git_hash": "a3f2b1c",
    "author": "John Doe",
    "source": "git"
  }
}

需求

• 必须安装Git
• 必须在git存储库中运行
• 提交必须存在于指定范围内

何时使用

• 会话开始：导入最近的提交以提供上下文
• 重大工作后：从工作会话导入提交
• 进度审查：查看实际承诺与计划
• 团队协作：从其他团队成员导入提交

未来改进

阶段2：上下文管理

• 上下文溢出检测：监控令牌使用情况并在限制前发出警告
• 智能摘要：自动压缩旧上下文，同时保留关键信息
• 令牌计数：估计上下文大小并针对模型限制进行优化

第三阶段：高级功能

• Q CLI集成：直接连接到Q的命令管道，实现无缝跟踪
• 上下文注入：启动时自动向Q提供会话上下文
• 智能恢复：检测未完成的会话并提供恢复
• 模式分析从成功的会议中学习，以改进建议
• 会话分析：跟踪成功率、常见故障模式和生产力指标
• 多代理支持：处理同时运行的多个Q代理
• 会话合并：跨不同目录组合相关会话
• 导出/导入：在团队成员或环境之间共享会话数据