Laravel Server

A small project & task manager exposed as a Model Context Protocol (MCP) server, built with laravel/mcp. It is a learning-oriented reference that exercises every core MCP primitive — Tools, Resources, and Prompts — over a deliberately simple domain (projects that contain tasks).

An MCP client (Claude Desktop, Cursor, Claude Code, or the built-in inspector) connects to the server over stdio and lets an AI create and track tasks, pull read-only context, and run reusable prompt templates.

Domain

• Project — name, description, and many tasks.
• Task — belongs to a project; has a title, description, due_date, a status (pending, in_progress, done) and a priority (low, medium, high, critical). A task is overdue when its due date has passed and it is not yet done.

Priorities carry a numeric weight (low = 1 … critical = 4) used to sort reports and triage overdue work.

Project structure

app/
├── Enums/          TaskStatus, TaskPriority (with label() / weight() helpers)
├── Models/         Project, Task
├── Mcp/
│   ├── Servers/    ProjectManagerServer — registers all primitives
│   ├── Tools/      The 5 callable actions
│   ├── Resources/  The 5 read-only resources
│   └── Prompts/    The 4 prompt templates
└── Support/        ReportBuilder — shared report aggregation

MCP primitives

🔧 Tools — actions the AI can invoke

Tool	Description
create-task-tool	Create a task under a project (title, description, priority, due date).
list-tasks-tool	List tasks with optional filters: project, status, priority, overdue.
update-task-status-tool	Move a task to a new status and report the before → after change.
delete-task-tool	Delete a task by id.
generate-report-tool	Aggregate tasks into a portfolio report as Markdown or JSON.

📚 Resources — read-only context addressed by URI

Resource	URI	Description
System documentation	documentation	Onboarding overview of the server and its entities.
Priority rules	priority-rules	The priority levels, their weights, and when to use each.
Task details	task://tasks/{task_id}	Full detail for a single task (templated).
Project summary	project://projects/{project_id}	Task counts by status, overdue count, next due (templated).
Report	report://reports/{format}	Whole-portfolio report in json or markdown (templated).

The report tool and the report resource share a single ReportBuilder so their numbers can never drift apart.

💬 Prompts — reusable, argument-driven templates

Prompt	Arguments	Description
plan-project-prompt	goal (required), deadline	Break a goal into a project plus milestone tasks.
decompose-task-prompt	task_id (required)	Split one real task into concrete subtasks.
review-overdue-tasks-prompt	project_id	Triage and re-prioritize overdue tasks.
daily-summary-prompt	project_id	Produce a stand-up style daily summary.

Getting started

composer install
php artisan migrate

# Seed at least one project so tasks have somewhere to live:
php artisan tinker --execute "App\Models\Project::factory()->create(['name' => 'Website Redesign']);"

The server is registered in routes/ai.php and exposed over stdio:

Mcp::local('project-manager', ProjectManagerServer::class);

Running & testing the server

# Interactive debugging — drive tools, resources and prompts by hand:
php artisan mcp:inspector project-manager

# Run the server over stdio (this is the command MCP clients launch;
# on its own it will appear to hang, waiting for JSON-RPC on stdin):
php artisan mcp:start project-manager

Connecting from an AI client

Claude Code

claude mcp add project-manager -- php "<full-path>/artisan" mcp:start project-manager

Claude Desktop — add to claude_desktop_config.json:

{
  "mcpServers": {
    "project-manager": {
      "command": "php",
      "args": ["<full-path>/artisan", "mcp:start", "project-manager"]
    }
  }
}

Passing the full path to artisan lets Laravel resolve the project root regardless of the client's working directory.