beads/integrations/beads-mcp/CHANGELOG.md

Changelog

All notable changes to beads-mcp will be documented in this file.

The format is based on Keep a Changelog, and this project adheres to Semantic Versioning.

[0.41.0] - 2024-12-30

Changed

• Minor maintenance release

[0.24.0] - 2024-01-15

Changed

Breaking: Context Engineering Optimizations

The ready() and list() MCP tools now return list[IssueMinimal] or CompactedResult instead of list[Issue]. This breaking change reduces context window usage by ~80%.

What changed:

• ready() returns list[IssueMinimal] | CompactedResult (was list[Issue])
• list() returns list[IssueMinimal] | CompactedResult (was list[Issue])
• show() still returns full Issue (unchanged)

IssueMinimal includes:

• id, title, status, priority, issue_type
• assignee, labels, dependency_count, dependent_count

IssueMinimal excludes (use show() for these):

• description, design, acceptance_criteria, notes
• created_at, updated_at, closed_at
• dependencies, dependents (full objects)

CompactedResult (returned when >20 results):

{
    "compacted": True,
    "total_count": 47,
    "preview": [/* first 5 IssueMinimal */],
    "preview_count": 5,
    "hint": "Use show(issue_id) for full details"
}

Migration guide:

1. Check for compacted results:

   if isinstance(response, dict) and response.get("compacted"):
       issues = response["preview"]
   else:
       issues = response
   

2. Use show() for full details:

   for issue in issues:
       full_issue = show(issue_id=issue.id)
       print(full_issue.description)
   

3. Available options for list operations:

   • brief=True - Returns BriefIssue (id, title, status, priority only)
   • fields=["id", "title"] - Custom field projection
   • max_description_length=100 - Truncate descriptions

Rationale:

• Reduces context usage from ~400 bytes/issue to ~80 bytes/issue
• Prevents context overflow for large issue lists (>20 items)
• Encourages efficient "list then show" pattern for AI agents

See CONTEXT_ENGINEERING.md for full migration guide.

Added

• discover_tools() - Lightweight tool catalog for lazy schema loading
• get_tool_info(tool_name) - On-demand tool details
• CompactedResult model for large result sets
• IssueMinimal model for list views
• BriefIssue model for ultra-compact responses
• brief, fields, max_description_length parameters for all list operations
• Environment variables for compaction tuning:
  • BEADS_MCP_COMPACTION_THRESHOLD (default: 20)
  • BEADS_MCP_PREVIEW_COUNT (default: 5)

[0.23.0] and earlier

See git history for changes prior to context engineering optimizations.