johno/beads
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Update README: Mark FastMCP outputSchema issue as resolved

Browse Source
This commit is contained in:
Steve Yegge
2025-11-23 22:13:44 -08:00
parent 1f27256525
commit 19e25f1aeb
1 changed files with 14 additions and 10 deletions
Download Patch File Download Diff File Expand all files Collapse all files

24
integrations/beads-mcp/README.md
View File

@@ -224,21 +224,25 @@ await beads_ready_work(workspace_root="/Users/you/project-a")
## Known Issues ## Known Issues
### MCP Tools Not Loading in Claude Code (Issue [#346](https://github.com/steveyegge/beads/issues/346)) ### ~~MCP Tools Not Loading in Claude Code~~ (Issue [#346](https://github.com/steveyegge/beads/issues/346)) - RESOLVED
**Status:** Blocked by upstream FastMCP bug ([#2455](https://github.com/jlowin/fastmcp/issues/2455)) **Status:** ✅ Fixed in v0.24.0+
MCP tools currently fail to load in Claude Code due to a schema generation bug in FastMCP 2.13.1. The issue affects self-referential Pydantic models and causes Claude Code to reject all beads MCP tools. This issue affected versions prior to v0.24.0. The problem was caused by self-referential Pydantic models (`Issue` with `dependencies: list["Issue"]`) generating invalid MCP schemas with `$ref` at root level.
**Workaround:** Use slash commands instead of MCP tools in Claude Code: **Solution:** The issue was fixed in commit f3a678f by refactoring the data models:
- `/beads:ready` instead of the `ready` MCP tool - Created `IssueBase` with common fields
- `/beads:show bd-123` instead of the `show` MCP tool - Created `LinkedIssue(IssueBase)` for dependency references
- `/beads:list` instead of the `list` MCP tool - Changed `Issue` to use `list[LinkedIssue]` instead of `list["Issue"]`
- etc.
Slash commands work because they call the `bd` CLI directly rather than going through the MCP tool interface. This breaks the circular reference and ensures all tool outputSchemas have `type: object` at root level.
**Resolution:** This will be fixed automatically once FastMCP releases a fix for their schema generation bug. The beads-mcp dependency will then be updated to use the fixed version. **Upgrade:** If you're running beads-mcp < 0.24.0:
```bash
pip install --upgrade beads-mcp
```
All MCP tools now load correctly in Claude Code with v0.24.0+.
## Development ## Development