Skip to content

MCP resources: decks, due-today, recent (#166) - #186

Merged
philphilphil merged 19 commits into
mainfrom
feat/mcp-resources
Jun 13, 2026
Merged

MCP resources: decks, due-today, recent (#166)#186
philphilphil merged 19 commits into
mainfrom
feat/mcp-resources

Conversation

@philphilphil

@philphilphil philphilphil commented May 28, 2026

Copy link
Copy Markdown
Owner

Closes #166.

Summary

Implements MCP resources for the Fasolt MCP server:

  • fasolt://deck/{deckId} — one entry per active deck the user owns
  • fasolt://due-today — singleton, cards due today grouped by deck
  • fasolt://recent — singleton, cards created in the last 7 days, newest first

Clients with @-resource pickers (Claude Code, Claude Desktop) can now attach these into a conversation by deck name. The deck mention syntax in Claude Code is @fasolt:fasolt://deck/<id>, surfaced in the autocomplete by human deck name.

Side effect: the resources/list and resources/templates/list "method not implemented" log lines from codex-mcp-client are gone — those endpoints now have real handlers.

Architecture

Pure handler-based MCP registration via WithListResourcesHandler, WithListResourceTemplatesHandler, WithReadResourceHandler in a new AddFasoltResources() extension. All rendering logic lives in McpResourceService (unit-testable). Auth pattern matches existing tools (McpUserResolver.GetUserId), with a localized try/catch that translates UnauthorizedAccessException into a clean MCP error.

Files:

  • fasolt.Server/Application/Services/McpResourceService.cs — rendering + queries
  • fasolt.Server/Api/McpResources/ResourceUris.cs — URI constants + parser
  • fasolt.Server/Api/McpResources/McpResourceHandlers.cs — handler delegate registration
  • fasolt.Server/Program.cs — .AddFasoltResources() in the AddMcpServer chain + # Resources note in ServerInstructions

Content shape

Each card renders as:

```markdown
Front: essen

Back: to eat

Source: notes/german/verbs.md
```

  • Back: block omitted if back is empty
  • *Source: ...* footer omitted if no source file
  • Cards with SVG: [has SVG image — use get_card for full content] (text-focused, keeps content bounded)

Truncation: 100 cards / 80 KB budget per resource with *Showing X of Y cards.* footer.

Test plan

  • 30 unit tests in fasolt.Tests/McpResourceServiceTests.cs cover deck/due-today/recent rendering, truncation, suspended-card and suspended-deck filtering, source/SVG handling, cross-user isolation, deck grouping with (no deck) bucket, lazy group-header emission on truncation boundaries.
  • 2 integration tests in fasolt.Tests/McpResourceEndpointTests.cs confirm McpResourceService resolves from the real DI container with a seeded user, and /mcp rejects unauthenticated callers.
  • Full suite: 356/356 pass, 0 warnings.

References

  • Design spec: docs/superpowers/specs/2026-05-28-mcp-resources-design.md
  • Implementation plan: docs/superpowers/plans/2026-05-28-mcp-resources.md

🤖 Generated with Claude Code

philphilphil and others added 19 commits May 28, 2026 12:58
@philphilphil @claude
docs(mcp): design for MCP resources (#166)
3df89d4 
Spec for exposing decks, due-today, and recent as MCP resources so
clients with @-pickers (Claude Code, Claude Desktop) can pin them
into conversations. Also resolves resources/list and
resources/templates/list 'method not implemented' log noise.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
@philphilphil @claude
docs(mcp): implementation plan for MCP resources (#166)
2eaedb2 
12 TDD tasks covering McpResourceService rendering, URI helpers,
handler registration in Program.cs, and integration tests.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
@philphilphil @claude
feat(mcp): scaffold McpResourceService with deck + statics listing
e0709d6 
Lists active decks plus two static resources (due-today, recent) for
the authenticated user. Render methods stubbed; subsequent tasks fill
them in.

Refs #166

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
@philphilphil @claude
feat(mcp): render deck resource markdown
6b87460 
Implements RenderDeckAsync with header (name, counts, description),
**Front:** / **Back:** card blocks, source footer, and SVG note.
Empty and missing decks handled.

Refs #166

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
@philphilphil @claude
test(mcp): verify deck rendering edges (suspended/source/svg/empty back)
10b5e17 
Refs #166

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
@philphilphil @claude
test(mcp): verify deck truncation at 100 cards and 80 KB budget
319edc0 
Refs #166

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
@philphilphil @claude
feat(mcp): render due-today resource grouped by deck
5c0617a 
Cards due now (or new), suspended cards/decks excluded, grouped by
first alphabetical deck name with a (no deck) bucket at the end.

Refs #166

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
@philphilphil @claude
fix(mcp): defer due-today group header until first card fits
3f10cb2 
Previously the '## DeckName (N cards)' header was written before the
inner card loop, so if truncation fired on the group's first card the
header appeared with nothing under it. Now the header is written lazily,
right before the first successful card append. Also adds the
"rendered > 0" guard to match AppendCardsWithTruncation so a single
oversized card still renders.

Refs #166

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
@philphilphil @claude
feat(mcp): render recent resource (last 7 days, newest first)
50d6312 
Excludes suspended cards. Each block carries Created date and first
non-suspended deck name as metadata.

Refs #166

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
@philphilphil @claude
test(mcp): cover list-resources ordering, suspended filter, isolation
4cf5036 
Refs #166

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
@philphilphil @claude
feat(mcp): URI constants and parser for fasolt:// resources
9de5e80 
Refs #166

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
@philphilphil @claude
feat(mcp): register MCP resource handlers and capability
4f51463 
Wires resources/list, resources/templates/list, resources/read into
the MCP server via AddFasoltResources(). Server now advertises the
resources capability. Eliminates 'method not implemented' log noise
for clients that probe these endpoints.

Refs #166

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
@philphilphil @claude
fix(mcp): translate auth failure to MCP error in resource handlers
d12d696 
McpUserResolver throws UnauthorizedAccessException; before this fix it
would propagate as a 500 from the resource handlers (the tool path is
already covered by AddCallToolFilter). Wraps the resolve call in a
small helper that re-throws as McpProtocolException with
McpErrorCode.InvalidRequest so the client gets a clean JSON-RPC error.

Refs #166

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
@philphilphil @claude
test(mcp): integration tests for MCP resource handlers
c054fdd 
Confirms McpResourceService resolves from the real DI container and
produces the expected entries for a seeded user, and that the /mcp
endpoint rejects unauthenticated callers.

Refs #166

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
@philphilphil @claude
test(mcp): clean up seeded user even when assertions fail
5731f9a 
Wraps the assertions in try/finally so the DELETE always runs, avoiding
orphaned rows in the shared test database when an assertion throws.

Refs #166

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
@philphilphil @claude
chore(mcp): drop unused ReviewService dep + reconcile spec source line
a4d151f 
Removes the ReviewService constructor parameter that was scaffolded
in Task 1 but never used; the EF queries in the render methods went
direct to AppDbContext. Test factory updated to match.

Also updates the design spec: the per-card source footer is now
'*Source: <file>*' without the '→ heading' suffix the original draft
implied, since Card.SourceHeading is not part of the data model.

Refs #166

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
@philphilphil @claude
log(mcp): info on resources/list+read, error on unexpected throws
8c703f8 
The tool path already does this via AddCallToolFilter in Program.cs;
resource handlers had no equivalent so an unexpected exception (e.g.
DB hiccup, EF projection failure) would surface to the SDK with no Seq
log entry. Matches the tool pattern: info on each call, error on
non-McpException / non-cancellation throws.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
@philphilphil @claude
perf(mcp): project HasSvg boolean + cap due-today query
882e6ac 
Resource render queries selected the full FrontSvg/BackSvg columns
(up to ~1MB each) only to null-check them for the "[has SVG image]"
placeholder. Project a HasSvg boolean instead so the payloads stay in
Postgres. Also add a hard pre-render cap to RenderDueTodayAsync
(QueryHardCap, matching RenderRecentAsync) with soonest-due ordering so
a large due backlog no longer materializes in full.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
@philphilphil @claude
fix(mcp): report true card counts in resources, independent of page cap
29abc6a 
Resource summaries/footers read counts from a separate COUNT query
instead of the materialized page, so they stay accurate when the result
set exceeds the 200-row page cap (e.g. "Showing 100 of 250 cards").
Also fix the deck list description to count only non-suspended cards,
matching the rendered deck body.

Refs #166

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
@philphilphil
philphilphil merged commit cfe56cd into main Jun 13, 2026
2 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

No reviews

Assignees

No one assigned

Labels

None yet

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

MCP Resources: expose decks as readable resources

1 participant

@philphilphil