Skip to content

Add MCP server for the roadmap - #364

Merged
Cannonb4ll merged 3 commits into
mainfrom
feature/mcp-server
Sep 28, 2026
Merged

Cannonb4ll merged 3 commits into
mainfrom
feature/mcp-server

Conversation

@Cannonb4ll

@Cannonb4ll Cannonb4ll commented Sep 28, 2026 •

Copy link
Copy Markdown
Member

Adds an MCP server built on laravel/mcp, so AI assistants (Claude, Cursor, etc.) can work with the roadmap as the user that owns the token.

Enabling

MCP is off by default. Admins turn it on under Settings → MCP. While it's off:

  • POST /mcp returns a 404, even with a valid token
  • the MCP section on the profile page is hidden
  • /mcp/docs returns a 404, except for admins and employees, who see it with a notice that MCP is disabled

Docs

/mcp/docs explains what the assistant can do, how to create a token and how to connect a client. It also lists the tools, read from RoadmapServer::TOOLS. The connection instructions have a tab per client, with copyable snippets:

  • Claude Code: claude mcp add --transport http …
  • Claude Desktop: claude_desktop_config.json via mcp-remote. The web version (claude.ai) only supports OAuth connectors, and the page says so.
  • ChatGPT: developer mode connector with "Access token / API key" authentication
  • Cursor, VS Code and Codex: config file snippets

The MCP tab in the admin settings shows the same instructions and tool list as soon as the toggle is switched on. The instructions live in shared components (resources/views/components/mcp/*), and admin.css sources them so Tailwind picks up their classes.

Endpoint & auth

  • POST /mcp, protected by auth:sanctum and the api rate limiter.
  • Users create and revoke tokens under MCP access on their profile page. The plain-text token is shown once.
  • New migration adds the expires_at column to personal_access_tokens. The table predates Sanctum 3, and token creation fails without it.

Tools

Tool Who What
list-projects everyone Visible projects with their boards (admins/employees also see hidden boards)
get-project everyone Project with boards and item count per board
list-items everyone Filter on project/board, search, sort (latest, popular, last_commented), paginated
get-item everyone Item content and comments (private notes only for admins/employees)
comment-on-item everyone Comment or reply. Private notes are admin/employee only. Follows the board's comment block and the verify-email setting
move-item admins/employees Move an item to another board, optionally in another project. Not registered for other users, and checked again in the handler

All lookups use the existing visibleForCurrentUser scopes, so private projects and items stay hidden exactly as on the site. Comments go through Comment::create, so mentions and notifications work the same as on the site.

Notes

  • Auth uses Sanctum rather than Passport/OAuth. Clients that only support OAuth (such as claude.ai web connectors) can't connect yet. Supporting them needs Passport and Mcp::oauthRoutes(), which can come in a follow-up.

Tests

  • tests/Feature/Mcp/*: visibility, filters, commenting rules, move permissions, and HTTP auth plus tool listing per role
  • tests/Feature/Livewire/ProfileMcpTokensTest.php: create, show once, revoke only your own tokens, hidden when disabled
  • tests/Feature/Controllers/McpControllerTest.php: docs page for guests and users, 404 when disabled, admin/employee access when disabled
  • tests/Feature/Filament/McpSettingsTest.php: off by default, admins can turn it on, instructions only show once it's on
  • Full suite: 380 passed

Adds a laravel/mcp server at /mcp, authenticated with Sanctum tokens that
users can create and revoke on their profile page. Tools respect the same
visibility rules as the site, and moving items is limited to admins and
employees.
MCP is off by default. Admins enable it under Settings > MCP. While it's off
the endpoint returns a 404 and the profile token section is hidden. The new
/mcp/docs page explains how to create a token and connect a client, and
lists the available tools.
…tings

The docs page and the MCP settings tab now share the same instructions for
Claude Code, Claude Desktop, ChatGPT, Cursor, VS Code and Codex. They show up
in the settings once MCP is enabled.
@Cannonb4ll
Cannonb4ll merged commit 64f6440 into main Sep 28, 2026
4 checks passed
@Cannonb4ll
Cannonb4ll deleted the feature/mcp-server branch September 28, 2026 10:56
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant