Which integrations are available for this server?

Retrieves information from local Git repositories, such as branch status, uncommitted changes, and commit history, to inform session state and management.

How do I use Claude Session MCP?

1. Click on "Install Server". 2. Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state. 3. In the chat, type @ followed by the MCP server name and your instructions, e.g., "@Claude Session MCP check context budget and tell me if I should reset" That's it! The server will respond to your query, and you can continue using it as needed. Here is a step-by-step guide with screenshots.

Claude Session MCP

by TimEvans

Overview Schema Related Servers Score Discussions

Python

Local

Claude Session MCP

An MCP (Model Context Protocol) server that provides Claude Code with programmatic session awareness - the ability to query context usage, read todos, track session history, sync planning docs, and make intelligent reset recommendations.

Why This Exists

Claude Code agents, slash commands, and hooks need to make smart decisions about session management:

Before spawning a sub-agent: Check if there's enough context budget remaining
Before expensive operations: Verify we're not at 90% context and about to trigger compaction
When resuming work: Know what todos are already in progress to avoid duplication
During long sessions: Programmatically update .context/dev/{branch}/ planning docs
End of task: Get intelligent recommendations on whether to reset context

This MCP server makes all of that possible by exposing session state through 5 core tools.

Related MCP server: claude-session-continuity-mcp

Features

5 Session Awareness Tools

Tool	Purpose	Use Cases
`check_context_budget`	Query context window usage and remaining capacity	Gate operations when context is critical, warn before spawning agents
`get_session_state`	Unified snapshot of todos, git state, context files, session info	Check existing todos before creating new ones, verify branch state
`get_session_history`	What's been accomplished (files modified, todos completed, commits)	Auto-generate session summaries, resume after context reset
`sync_planning_doc`	Programmatically update `.context/dev/{branch}/` planning docs	Log decisions as you work, mark tasks complete in real-time
`should_reset_context`	Intelligent recommendations for when to reset context	End-of-task automation, proactive warnings

Installation

Prerequisites

Python 3.11+ (tested on 3.13)
uv package manager
Claude Code CLI

Install Steps

# Clone the repository
git clone https://github.com/yourusername/ccsession
cd ccsession

# Install with uv
uv venv
uv pip install -e ".[dev]"

Configuration

Option 1: Global Configuration

Add to ~/.claude/mcp.json:

{
  "mcpServers": {
    "ccsession": {
      "command": "uv",
      "args": ["run", "python", "-m", "ccsession"],
      "cwd": "/home/your-username/path/to/ccsession"
    }
  }
}

Option 2: Project-Level Configuration

Add to <your-project>/.claude/mcp.json:

{
  "mcpServers": {
    "ccsession": {
      "command": "uv",
      "args": ["run", "python", "-m", "ccsession"],
      "cwd": "/home/your-username/path/to/ccsession"
    }
  }
}

Verify Installation

After restarting Claude Code, the tools will be available to agents and slash commands. You can verify by asking:

"Can you check the context budget using the MCP tools?"

Tool Reference

1. `check_context_budget`

Query current context window usage and remaining capacity.

Parameters:

context_limit (optional): Maximum context tokens. Default: 156,000 (200K × 0.78 threshold)

Returns:

{
  "tokens_used": 45230,
  "tokens_remaining": 110770,
  "percentage_used": 29.0,
  "context_limit": 156000,
  "status": "sufficient"
}

Status Values:

sufficient: < 60% used
low: 60-80% used
critical: > 80% used

Example Usage in Slash Command:

<!-- .claude/commands/check-budget.md -->
Use the `check_context_budget` MCP tool to see how much context we have left.

If status is "critical", warn me and recommend resetting context.

2. `get_session_state`

Get a unified snapshot of current session state.

Parameters:

working_directory (optional): Working directory for git operations. Defaults to current directory.

Returns:

{
  "todos": {
    "pending": [
      {
        "content": "Deploy to production",
        "status": "pending",
        "activeForm": "Deploying to production"
      }
    ],
    "in_progress": [
      {
        "content": "Update documentation",
        "status": "in_progress",
        "activeForm": "Updating documentation"
      }
    ],
    "completed": [
      {
        "content": "Implement auth middleware",
        "status": "completed",
        "activeForm": "Implementing auth middleware"
      }
    ]
  },
  "git": {
    "branch": "feat/auth",
    "has_uncommitted_changes": true,
    "uncommitted_file_count": 3,
    "is_git_repo": true
  },
  "context_files": {
    "branch_dir": ".context/dev/feat/auth",
    "plan_path": ".context/dev/feat/auth/feat-auth-detailed-plan.md",
    "exists": true
  },
  "session": {
    "start_time": "2025-12-03T14:00:00+00:00",
    "duration_minutes": 45,
    "session_id": "73cc9f9a-1234-5678-9abc-def012345678"
  }
}

Example Usage in Agent:

# Before creating new todos, check what's already in progress
state = await get_session_state()

if any(t["content"] == "Implement authentication" for t in state["todos"]["in_progress"]):
    print("Authentication implementation already in progress, skipping duplicate todo")

3. `get_session_history`

Get what has been accomplished this session.

Parameters:

working_directory (optional): Working directory for git operations. Defaults to current directory.

Returns:

{
  "completed_todos": [
    "Implement auth middleware",
    "Add tests",
    "Update documentation"
  ],
  "files_modified": {
    "created": ["src/auth/middleware.ts"],
    "edited": ["src/server.ts", "README.md"],
    "deleted": []
  },
  "tool_calls": {
    "bash_commands": ["npm test", "git commit -m 'feat: add auth'"],
    "agents_spawned": ["Explore", "Plan"],
    "files_read": 23,
    "files_written": 5
  },
  "git_commits": [
    {
      "sha": "a3f5d2c",
      "message": "feat(auth): add middleware"
    }
  ]
}

Example Usage in /reset-context Command:

<!-- .claude/commands/reset-context.md -->
1. Use `get_session_history` to see what was accomplished
2. Generate a concise summary from completed_todos and git_commits
3. Save summary to `.context/session-summaries/{date}-{session-id}.md`
4. Reset context with summary as reload context

4. `sync_planning_doc`

Programmatically update .context/dev/{branch}/ planning documents.

Parameters:

mode (required): One of:
- append_progress_log: Add timestamped entry to Progress Log
- update_active_work: Replace Active Work section
- mark_tasks_complete: Mark tasks as [x] in Implementation Plan
completed_tasks (array): Tasks completed (for append_progress_log or mark_tasks_complete)
in_progress (string): Current work description (for update_active_work)
decisions (array): Key decisions made (for append_progress_log)
blockers (array): Current blockers (for update_active_work or append_progress_log)
next_steps (array): Next immediate steps (for update_active_work)
working_directory (optional): Working directory. Defaults to current directory.

Returns:

{
  "success": true,
  "plan_path": ".context/dev/feat-auth/feat-auth-detailed-plan.md",
  "sections_updated": ["Progress Log"]
}

Example 1: Append Progress Log

{
  "mode": "append_progress_log",
  "completed_tasks": ["Phase 1.1: Database schema", "Phase 1.2: API endpoints"],
  "decisions": ["Using bcrypt for password hashing", "JWT tokens expire after 24h"],
  "blockers": []
}

Example 2: Update Active Work

{
  "mode": "update_active_work",
  "in_progress": "Implementing user registration endpoint",
  "next_steps": [
    "Add input validation",
    "Write unit tests",
    "Test with Postman"
  ],
  "blockers": ["Waiting for design review on error messages"]
}

Example 3: Mark Tasks Complete

{
  "mode": "mark_tasks_complete",
  "completed_tasks": [
    "Implement authentication",
    "Write tests"
  ]
}

This will change:

- [ ] Implement authentication
- [ ] Write tests

To:

- [x] Implement authentication
- [x] Write tests

5. `should_reset_context`

Get intelligent recommendation on whether to reset context.

Parameters:

working_directory (optional): Working directory. Defaults to current directory.

Returns:

{
  "should_reset": true,
  "confidence": "high",
  "reasoning": [
    "Context 82% full (critical threshold)",
    "All in_progress todos completed",
    "Clean git state (no uncommitted changes)",
    "Session duration: 2h 15m"
  ],
  "safe_to_reset": true,
  "blockers": [],
  "suggested_summary": "Completed: auth middleware, tests, documentation"
}

Decision Logic:

Condition	Recommendation
Context >80% + clean git + todos done	`should_reset: true`, `confidence: high`
Context 60-80% + todos done + clean git	`should_reset: true`, `confidence: high`
Context 60-80% + clean git	`should_reset: true`, `confidence: medium`
Context >60% + uncommitted changes	`should_reset: false`, `safe_to_reset: false`
Session >60min + todos done + clean git	`should_reset: true`, `confidence: medium`

Example Usage in Hook:

// .claude/hooks/before-agent-spawn.json
{
  "command": "bash -c 'claude-code mcp call should_reset_context | jq -r .should_reset'",
  "on_success": "proceed",
  "on_failure": "warn"
}

Use Cases

Use Case 1: Smart Agent Spawning

Problem: Agent spawns a sub-agent, but context is at 85%, causing immediate compaction and lost context.

Solution:

<!-- In your agent prompt -->
Before spawning any sub-agents, ALWAYS:

1. Call `check_context_budget`
2. If status is "critical" or "low", call `should_reset_context`
3. If reset recommended, warn user and ask permission before proceeding

Use Case 2: Avoid Duplicate Todos

Problem: After context reset, agent creates duplicate todos for work already in progress.

Solution:

<!-- In your slash command -->
Before creating todos:

1. Call `get_session_state`
2. Check if any `todos.in_progress` or `todos.pending` match your planned work
3. Only create new todos for work not already tracked

Use Case 3: Real-Time Planning Doc Updates

Problem: Planning docs in .context/dev/{branch}/ only get updated at end of session, losing valuable decision history.

Solution:

<!-- In your agent prompt -->
After completing each major task:

1. Call `sync_planning_doc` with mode="append_progress_log"
2. Include completed_tasks and any key decisions made
3. This keeps planning docs as living documents

Use Case 4: Automated Session Summaries

Problem: Manually writing session summaries before context reset is tedious and error-prone.

Solution:

<!-- .claude/commands/auto-reset.md -->
1. Call `get_session_history` to get completed_todos and git_commits
2. Generate 2-3 sentence summary
3. Call `should_reset_context` to verify safe to reset
4. If safe, save summary and reset context with /reset command

Architecture

How It Works

Transcript Discovery: Scans /tmp/claude-code-transcripts/ for the most recent .jsonl file
Token Counting: Parses transcript to sum input_tokens + output_tokens + cache_creation_input_tokens + cache_read_input_tokens
Todo Parsing: Reads ~/.claude/todos/{session_id}*.json files (handles agent spawns)
Git Operations: Subprocess calls to git CLI for branch, status, commits
Planning Doc Updates: Markdown section parsing with regex, preserves formatting

File Locations

~/.claude/
├── todos/{session_id}.json              # Main session todos
├── todos/{session_id}-agent-*.json      # Agent spawn todos
└── mcp.json                              # MCP server config

/tmp/claude-code-transcripts/
└── {session_id}.jsonl                    # Session transcript

<project>/.context/dev/{branch}/
└── {branch}-detailed-plan.md             # Planning document

Context Limit Calculation

Claude Code triggers /compact at ~78% of the 200K context window:

DEFAULT_CONTEXT_LIMIT = int(200_000 * 0.78)  # 156,000 tokens

Thresholds:

Sufficient: < 60% of limit (< 93,600 tokens)
Low: 60-80% of limit (93,600 - 124,800 tokens)
Critical: > 80% of limit (> 124,800 tokens)

Development

Running Tests

# Run all tests
uv run pytest

# Run with verbose output
uv run pytest -v

# Run specific test file
uv run pytest tests/test_transcript.py

# Run with coverage
uv run pytest --cov=ccsession

Test Coverage

47 passing tests covering:
- Transcript parsing (token counting, session start time, edge cases)
- Git utilities (state detection, commits, planning doc paths)
- Todo parsing (session todos, agent spawns, latest todos)
- All 5 MCP tools (integration tests with mocked dependencies)

Project Structure

ccsession/
├── src/ccsession/
│   ├── __init__.py
│   ├── __main__.py              # Entry point
│   ├── server.py                # MCP server + all 5 tools
│   └── parsers/
│       ├── transcript.py        # JSONL parsing, token counting
│       ├── git.py               # Git operations
│       └── todos.py             # Todo file parsing
├── tests/
│   ├── conftest.py              # Shared fixtures
│   ├── test_transcript.py       # Transcript parser tests
│   ├── test_git.py              # Git utilities tests
│   ├── test_todos.py            # Todo parser tests
│   ├── test_mcp_tools.py        # Integration tests
│   └── fixtures/                # Test data
├── pyproject.toml               # Package config
└── README.md

Adding New Features

New parser: Add to src/ccsession/parsers/
New tool: Add handler in server.py under handle_tool_call()
Add tests: Create tests/test_*.py with fixtures
Update docs: Document in this README

Troubleshooting

MCP server not found

Error: MCP server 'claude-session' not found

Solution:

Check ~/.claude/mcp.json or <project>/.claude/mcp.json exists
Verify cwd path points to correct directory
Restart Claude Code to reload MCP config

No transcript found

Error: Tools return empty/zero values

Solution:

Verify /tmp/claude-code-transcripts/ directory exists
Check that .jsonl files are being created during sessions
MCP uses most recent file by modification time

Planning doc not found

Error: sync_planning_doc returns "Plan file not found"

Solution:

Verify .context/dev/{branch}/{branch}-detailed-plan.md exists
Check you're on the correct git branch
Planning doc path follows pattern: branch name with dashes, not slashes

Tests failing

Error: Import errors or test failures

Solution:

# Reinstall in development mode
uv pip install -e ".[dev]"

# Clear pytest cache
rm -rf .pytest_cache

# Run with full traceback
uv run pytest -v --tb=long

Acknowledgments

Transcript parsing logic ported from ccusage by @ryoppippi
Built with the MCP Python SDK
Designed for Claude Code

License

MIT License - see LICENSE file for details

Contributing

Contributions welcome! Please:

Fork the repository
Create a feature branch (git checkout -b feat/amazing-feature)
Add tests for new functionality
Ensure all tests pass (uv run pytest)
Submit a pull request

Future Enhancements

Potential Wave 2+ features (see PLAN.md for full list):

Session comparison: Diff two sessions to see what changed
Cost tracking: Token usage → USD cost estimates
Time tracking: How long was spent on each task
Planning doc templates: Auto-generate planning docs from templates
Multi-session search: Find when/where specific work was done
Session replay: Reconstruct what happened in a previous session

See something missing? Open an issue!

Available Tools

5 tools

check_context_budgetA

Check current context window usage and remaining capacity. Returns tokens used, remaining, percentage, and status (sufficient/low/critical).

ParametersJSON Schema

Name	Required	Description	Default
`context_limit`	No	Maximum context tokens. Default: 156000 (200K * 0.78)

TDQS

A3.8/5.0

Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations provided, the description carries the full burden of behavioral disclosure. It describes the tool as a read-only check operation and details the return values (tokens used, remaining, etc.), which is helpful. However, it lacks information on potential side effects, error conditions, or performance characteristics, leaving gaps in behavioral understanding for a tool with no annotation support.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is extremely concise and front-loaded, consisting of two sentences that efficiently convey the tool's purpose and return values without any wasted words. Every sentence earns its place by providing essential information, making it easy for an agent to parse and understand quickly.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool's low complexity (one optional parameter, no output schema, no annotations), the description is reasonably complete. It explains what the tool does and what it returns, which is sufficient for basic usage. However, the lack of output schema means the description could benefit from more detail on return formats or examples, slightly limiting completeness.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The input schema has 100% description coverage, documenting the single optional parameter (context_limit) with its type, default, and purpose. The description does not add parameter details beyond the schema, but with only one optional parameter and high schema coverage, this is acceptable. The baseline is 3, but the simplicity and full schema coverage justify a 4.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool's purpose with specific verbs ('check', 'returns') and resources ('context window usage and remaining capacity'), distinguishing it from siblings like get_session_history or sync_planning_doc. It explicitly lists what information is returned (tokens used, remaining, percentage, status), making the purpose unambiguous and distinct.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides no guidance on when to use this tool versus alternatives or in what context it should be invoked. It does not mention prerequisites, timing, or comparisons to sibling tools like should_reset_context, leaving the agent to infer usage based solely on the purpose statement.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

get_session_historyB

Get what has been accomplished this session - completed todos, files modified, tool calls, git commits.

ParametersJSON Schema

Name	Required	Description	Default
`working_directory`	No	Working directory for git operations. Defaults to current directory.

TDQS

B3.1/5.0

Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, so the description carries the full burden of behavioral disclosure. While it implies a read-only operation ('get'), it doesn't specify whether this requires permissions, how data is formatted or returned, if there are rate limits, or what happens with errors. For a tool with zero annotation coverage, this is a significant gap in behavioral context.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single, efficient sentence that directly states the tool's purpose with specific examples. It's front-loaded with the core function and avoids unnecessary words, making it easy for an agent to parse quickly.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool's moderate complexity (retrieving session history) and the absence of annotations and output schema, the description is minimally adequate. It covers what data is retrieved but lacks details on return format, error handling, or behavioral traits. With no output schema, the agent must infer return values from the description alone, which is incomplete.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The schema description coverage is 100%, so the input schema already documents the single parameter 'working_directory' with its type and default. The description adds no additional parameter information beyond what the schema provides, such as examples or edge cases. Baseline 3 is appropriate when the schema handles parameter documentation adequately.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool's purpose: to retrieve session history including completed todos, files modified, tool calls, and git commits. It specifies the verb 'get' and the resource 'session history' with concrete examples of what's included. However, it doesn't explicitly differentiate from sibling tools like 'get_session_state' or 'check_context_budget', which prevents a perfect score.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides no guidance on when to use this tool versus alternatives. It doesn't mention when this tool is appropriate, when not to use it, or how it differs from sibling tools such as 'get_session_state' or 'should_reset_context'. This leaves the agent without contextual usage information.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

get_session_stateB

Get unified snapshot of current session state including todos, git status, context files, and session info.

ParametersJSON Schema

Name	Required	Description	Default
`working_directory`	No	Working directory for git operations. Defaults to current directory.

TDQS

B3.1/5.0

Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, so the description carries the full burden of behavioral disclosure. It describes what the tool returns (a snapshot of session state) but lacks details on behavioral traits such as whether it's read-only, if it requires specific permissions, how it handles errors, or if there are rate limits. This is a significant gap for a tool with no annotation coverage.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single, efficient sentence that front-loads the key information ('Get unified snapshot of current session state') and lists specific components without unnecessary details. It is appropriately sized and has zero waste, making it easy for an agent to parse quickly.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool's complexity (a state snapshot tool with one optional parameter), no annotations, and no output schema, the description is moderately complete. It specifies what the snapshot includes, but lacks details on output format, behavioral context, or usage guidelines. This is adequate as a minimum viable description but has clear gaps in providing full context for effective tool invocation.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The input schema has 100% description coverage, with one optional parameter ('working_directory') fully documented in the schema. The description does not add any meaning beyond the schema, as it does not mention parameters or their semantics. Given the high schema coverage, the baseline score of 3 is appropriate, as the schema handles the parameter documentation adequately.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool's purpose with a specific verb ('Get') and resource ('unified snapshot of current session state'), listing key components like todos, git status, context files, and session info. However, it does not explicitly differentiate from sibling tools like 'get_session_history' or 'check_context_budget', which might also involve session-related data, leaving some ambiguity in sibling differentiation.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides no guidance on when to use this tool versus alternatives. It does not mention any context for usage, such as when a snapshot is needed, or refer to sibling tools like 'get_session_history' for historical data or 'check_context_budget' for budget checks, leaving the agent without explicit usage instructions.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

should_reset_contextC

Get intelligent recommendation on whether to reset context. Analyzes context usage, todo completion, git state, and session duration.

ParametersJSON Schema

Name	Required	Description	Default
`working_directory`	No	Working directory for git operations. Defaults to current directory.

TDQS

C2.9/5.0

Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, so the description carries the full burden of behavioral disclosure. It states the tool 'analyzes' and provides a 'recommendation', implying a read-only, non-destructive operation, but doesn't clarify output format, potential side effects, or error handling. For a tool with zero annotation coverage, this is insufficient to inform the agent adequately about its behavior.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is concise and front-loaded, stating the core purpose in the first sentence. It efficiently lists analysis criteria without unnecessary elaboration. However, it could be slightly more structured by explicitly separating the recommendation output from the analysis inputs, but overall, it avoids waste and is appropriately sized.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness2/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool's complexity (involving multiple analysis factors) and the absence of annotations and output schema, the description is incomplete. It doesn't explain what the recommendation output looks like (e.g., boolean, score, rationale), how the analysis is performed, or any limitations. For a tool with no structured output information, this leaves significant gaps for the agent.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The input schema has 100% description coverage, with one optional parameter ('working_directory') well-documented in the schema. The description adds no parameter-specific information beyond what the schema provides, such as how 'working_directory' influences the analysis. Given the high schema coverage, a baseline score of 3 is appropriate, as the description doesn't compensate but also doesn't detract.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool's purpose: 'Get intelligent recommendation on whether to reset context.' It specifies the verb ('get recommendation') and the resource ('reset context'), and mentions the analysis criteria (context usage, todo completion, git state, session duration). However, it doesn't explicitly differentiate from sibling tools like 'check_context_budget' or 'get_session_state', which might overlap in monitoring context-related metrics.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides no guidance on when to use this tool versus alternatives. It mentions what the tool analyzes but doesn't specify scenarios for invocation, prerequisites, or comparisons to siblings like 'check_context_budget' or 'get_session_history'. This lack of contextual usage information leaves the agent without clear direction.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

sync_planning_docC

Update .context/dev/{branch}/ planning documents. Can append to progress log, update active work, or mark tasks complete.

ParametersJSON Schema

Name	Required	Description
`mode`	Yes	Update mode: append_progress_log, update_active_work, or mark_tasks_complete
`completed_tasks`	No	List of completed task descriptions (for append_progress_log or mark_tasks_complete)
`in_progress`	No	Current work in progress (for update_active_work)
`decisions`	No	Key decisions made (for append_progress_log)
`blockers`	No	Current blockers or issues (for update_active_work)
`next_steps`	No	Next immediate steps (for update_active_work)
`working_directory`	No	Working directory for git operations. Defaults to current directory.

TDQS

C2.9/5.0

Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations provided, the description carries the full burden of behavioral disclosure. It indicates this is a mutation tool ('Update'), but doesn't disclose permissions needed, whether changes are reversible, rate limits, or what happens to the planning documents. The description mentions what can be done but not the behavioral implications.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is appropriately concise with two sentences that efficiently convey the tool's purpose and capabilities. It's front-loaded with the main action and resource, followed by specific operations. No wasted words or redundant information.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness2/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a mutation tool with 7 parameters and no annotations or output schema, the description is insufficient. It doesn't explain the expected outcome format, error conditions, or how the different modes affect the planning documents. The agent would need to guess about the tool's behavior and results.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so the schema already documents all 7 parameters thoroughly. The description doesn't add any parameter-specific information beyond what's in the schema descriptions, so it meets the baseline for high schema coverage.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the action ('Update') and target resource ('.context/dev/{branch}/ planning documents'), and specifies three specific operations (append to progress log, update active work, mark tasks complete). However, it doesn't differentiate this tool from sibling tools, which appear unrelated to planning document management.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides no guidance on when to use this tool versus alternatives, prerequisites, or contextual triggers. It lists three modes but doesn't explain when each mode is appropriate or how they relate to different planning scenarios.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections. Dates show when Glama detected each change.

5 tool updatesv0.1.0Mar 21, 2026
- First observedcheck_context_budget
- First observedget_session_history
- First observedget_session_state
- First observedshould_reset_context
- First observedsync_planning_doc

Install Server

RayrunBuild, deploy, and operate MCP servers without becoming an infrastructure team.ray.runAd

TDQS

A3.5/5.0

Disambiguation5/5

Each tool has a clearly distinct purpose with no overlap: checking context budget, retrieving session history, getting session state, recommending context resets, and syncing planning documents. The descriptions clearly differentiate their functions, making misselection unlikely.

Naming Consistency4/5

Most tools follow a consistent verb_noun pattern (check_context_budget, get_session_history, get_session_state, sync_planning_doc), but 'should_reset_context' deviates slightly by using 'should' instead of a direct action verb. Overall, the naming is readable and predictable with only minor inconsistency.

Tool Count5/5

With 5 tools, this server is well-scoped for session management and context tracking. Each tool serves a specific, necessary function in this domain, and the count is neither too thin nor excessive for the apparent purpose.

Completeness4/5

The tool set covers core session management needs: monitoring context usage, tracking history and state, providing reset recommendations, and updating planning documents. A minor gap exists in direct context reset or modification tools, but agents can work around this using existing tools like 'should_reset_context' for guidance.

Maintenance

ActivityInactive

ResponsivenessSyncing

Resources

GitHub Repository

Need Help?

Related Servers

Unclaimed servers have limited discoverability.

Looking for Admin?

If you are the server author, to access and configure the admin panel.

Related MCP Connectors

ThreadminderOAuth
ai.threadminder
Persistent context for Claude. Your AI always knows your projects and next actions across sessions.
Knowledge & Memory Project Management
2
suma-memory A
io.github.sumanaddanki
Persistent memory for Claude Code and Cursor. Stop re-explaining your project every session.
Knowledge & Memory Developer Tools Autonomous Agents
2
PAPI: Persistent Adaptive Project IntelligenceOAuth
io.github.getpapi
Adaptive plan/build/review cycles for AI coding assistants, persisted across sessions.
Coding Agents Autonomous Agents
27
oneda
com.freeelatech
Persistent, governed institutional memory for Claude Code — specs, decisions, learnings.
Knowledge & Memory Documentation Access Note Taking
1

Related MCP Servers

Session Buddy
Knowledge & Memory Developer Tools Autonomous Agents
lesleslie
A
license
A
quality
C
maintenance
Provides comprehensive session management for Claude Code with automatic initialization/cleanup, quality checkpoints, and local conversation memory with semantic search for capturing learnings across coding sessions.
Updated a day ago (2026-09-05 10:04 UTC)
6
2
BSD 3-Clause
claude-session-continuity-mcp
Knowledge & Memory Developer Tools
leesgit
A
license
A
quality
A
maintenance
Zero-config session continuity for Claude Code. Automatically captures and restores project context across sessions using Claude Hooks.
Updated a month ago (2026-08-10 06:53 UTC)
25
32
5
MIT
backlog
Developer Tools
backloghq
A
license
A
quality
D
maintenance
Persistent, cross-session task management for Claude Code. 24 MCP tools for tasks, projects, dependencies, and docs. 7 skills for planning, standups, and handoffs. Event-sourced storage with per-project isolation.
Updated 3 months ago (2026-05-30 12:50 UTC)
5
MIT
mcp-session-insight
Observability Developer Tools
ArtLjn
A
license
A
quality
C
maintenance
Enables AI assistants to query and analyze past Claude Code sessions, providing structured insights like file changes, decisions, errors, and git history across projects.
Updated 3 months ago (2026-06-03 09:40 UTC)
11
20
1
MIT

Latest Blog Posts

Who's Calling? MCP Hosts Are an Identity Blind Spot (And the Spec Knows It)
By Om-Shree-0709 on July 25, 2026.
mcp
Agent Identity
OAuth 2.1
Your AI Chatbot Just Exposed Your CEO's Salary to an Intern
By Om-Shree-0709 on July 2, 2026.
Agent Identity
MCP Security
OAuth Delegation
Why MCP Servers Need Execution Sandboxing (And Why Your Current Stack Isn't Enough)
By Om-Shree-0709 on June 30, 2026.
Agentic Ai
Prompt Injection
WebAssembly

MCP directory API

We provide all the information about MCP servers via our MCP API.

curl -X GET 'https://glama.ai/api/mcp/v1/servers/TimEvans/ccsession'

If you have feedback or need assistance with the MCP directory API, please join our Discord server

Claude Session MCP

Why This Exists

Features

5 Session Awareness Tools

Installation

Prerequisites

Install Steps

Configuration

Option 1: Global Configuration

Option 2: Project-Level Configuration

Verify Installation

Tool Reference

1. check_context_budget

2. get_session_state

3. get_session_history

4. sync_planning_doc

5. should_reset_context

Use Cases

Use Case 1: Smart Agent Spawning

Use Case 2: Avoid Duplicate Todos

Use Case 3: Real-Time Planning Doc Updates

Use Case 4: Automated Session Summaries

Architecture

How It Works

File Locations

Context Limit Calculation

Development

Running Tests

Test Coverage

Project Structure

Adding New Features

Troubleshooting

MCP server not found

No transcript found

Planning doc not found

Tests failing

Acknowledgments

License

Contributing

Future Enhancements

Available Tools

Tool Schema Changelog

Maintenance

Resources

Looking for Admin?

Related MCP Connectors

Related MCP Servers

Latest Blog Posts

MCP directory API

1. `check_context_budget`

2. `get_session_state`

3. `get_session_history`

4. `sync_planning_doc`

5. `should_reset_context`