Harborboard
by ali-dev5490
README.md
# Harborboard
The [Model Context Protocol](https://modelcontextprotocol.io) lets an AI client call tools, read resources, and fetch prompts from a server you control. Harborboard is a Laravel app that exposes a real classifieds CRM — listings, leads, and orders — through that protocol.
It is a portfolio piece for MCP, AI integration, and SaaS work: a small domain with authorization, two transports, and tests, rather than a single hard-coded tool.
## Package choice
This app uses [laravel/mcp](https://packagist.org/packages/laravel/mcp) **1.2.1** (constraint `^1.2`), the official Laravel package. It is stable, it requires Laravel `12.41.1` or `13`, and the [framework docs](https://laravel.com/docs/12.x/mcp) describe its tools, resources, prompts, stdio server, and streamable HTTP server. The app itself is Laravel **12.73** on PHP **8.3+** (developed and tested on 8.4).
[mcp/sdk](https://github.com/modelcontextprotocol/php-sdk) is the official framework-agnostic PHP SDK. It is still marked experimental before 1.0, so it is a better fit outside Laravel. `php-mcp/server` is unmaintained. Laravel MCP is the right dependency for this codebase.
HTTP authentication uses [Laravel Sanctum](https://laravel.com/docs/12.x/sanctum) personal access tokens. Laravel's MCP guide recommends Sanctum when the application does not already run Passport, and recommends Passport when a client can only authenticate with OAuth 2.1. Passport, including the discovery routes Laravel MCP registers, is listed on the roadmap below.
## Architecture
```mermaid
flowchart LR
subgraph clients [MCP clients]
Claude[Claude Desktop]
Cursor[Cursor]
Inspector[MCP Inspector]
end
subgraph transports [Transports]
Stdio["stdio\nphp artisan mcp:start harbor"]
Http["Streamable HTTP\nPOST /mcp/harbor"]
end
subgraph app [Harborboard]
Sanctum[Sanctum ability mcp:use]
Limit[Rate limit]
Server[HarborServer]
Tools[Tools]
Resources[Resources]
Prompts[Prompts]
DB[(Workspace database)]
end
Claude --> Stdio
Cursor --> Stdio
Inspector --> Stdio
Inspector --> Http
Http --> Sanctum --> Limit --> Server
Stdio --> Server
Server --> Tools --> DB
Server --> Resources --> DB
Server --> Prompts --> DB
```
`routes/ai.php` registers one server twice:
- `Mcp::local('harbor', HarborServer::class)` starts as `php artisan mcp:start harbor` for Claude Desktop, Cursor, and MCP Inspector.
- `Mcp::web('/mcp/harbor', HarborServer::class)` is the streamable HTTP endpoint. It requires `auth:sanctum`, a token ability of `mcp:use` (or `*`), and the `mcp` rate limiter (60 requests per minute by default).
The stdio process has no HTTP user. It acts as `HARBOR_LOCAL_USER` (the seeded owner). That fallback is refused for web requests and for the test suite.
## What the domain contains
Northline Studio is a seeded workspace that sells furniture and lighting. Members share one workspace and have a role:
| Role | Read | Create and update leads, place orders | Archive listings |
| --- | --- | --- | --- |
| Viewer | Yes | No | No |
| Agent | Yes | Yes | No |
| Owner | Yes | Yes | Yes |
Write tools that a role cannot use are omitted from `tools/list`, so the model is not invited to call them. Policies still run inside the handler.
Seeded people (local fixtures, password `password`):
| Email | Name | Role |
| --- | --- | --- |
| `owner@harborboard.test` | Avery Chen | owner |
| `agent@harborboard.test` | Jordan Hale | agent |
| `viewer@harborboard.test` | Sam Okonkwo | viewer |
Seeded catalog:
| Slug | Status | Price |
| --- | --- | --- |
| `oak-writing-desk` | published | 840.00 USD |
| `linen-lounge-chair` | published | 620.00 USD |
| `brass-arc-lamp` | published | 310.00 USD |
| `walnut-media-console` | draft | 1290.00 USD |
| `ceramic-table-lamps` | sold | 180.00 USD |
| `marble-side-table` | archived | 450.00 USD |
Maya Ellis is a qualified lead on the oak desk. Chris Patel is a new lead on the lounge chair. Priya Shah already has fulfilled order `HB-1-0001`.
## Tools
Prices in arguments are major currency units (`700` means 700.00). Prices in results are decimal strings with a currency code.
| Tool | Access | What it does |
| --- | --- | --- |
| `search-listings` | read | Text, status, category, price range, sort, paging |
| `get-listing` | read | One listing by id or slug, with lead counts |
| `search-leads` | read | Text, status, listing, assignee |
| `get-lead` | read | One lead plus its activity history |
| `pipeline-summary` | read | Counts, money by order status, leads that need attention |
| `search-orders` | read | Orders, optionally by status |
| `create-lead` | agent, owner | Validates and writes immediately. An `idempotency_key` returns the original lead on retry |
| `update-lead-status` | agent, owner | Moves `new`, `contacted`, `qualified`, and `lost`. Repeating the same status is a no-op. `converted` is rejected |
| `place-order` | agent, owner | Preview unless `confirm` is `true`. A confirmed call creates the order, converts the lead, and marks the listing sold |
| `archive-listing` | owner | Preview unless `confirm` is `true`. The preview includes open leads. Archiving twice is safe |
`place-order` and `archive-listing` are the confirmation gate. The first call, with `confirm` omitted or `false`, returns `requires_confirmation: true` and writes nothing. A second call with `confirm: true` commits. A model that guesses an order still has to pass that flag, and the host should show the preview to a person before it does.
## Resources and prompts
| Kind | Name | URI or arguments |
| --- | --- | --- |
| Resource | `workspace-overview` | `harbor://workspace/overview` |
| Resource | `qualification-playbook` | `harbor://playbook/qualification` |
| Resource template | `listing` | `harbor://listings/{listing}` |
| Resource template | `lead` | `harbor://leads/{lead}` |
| Prompt | `qualify-lead` | `lead_id`, optional `tone` (`direct`, `warm`, `concise`) |
| Prompt | `draft-follow-up` | `lead_id`, optional `channel` (`email`, `sms`) |
| Prompt | `weekly-pipeline-review` | optional `focus` (`listings`, `leads`, `orders`, `all`) |
Prompts embed the current database row. They do not send email or change statuses.
## Quick start
Requirements: PHP 8.3 or 8.4 with `mbstring`, `xml`, `curl`, `sqlite`, `zip`, `bcmath`, and `intl`, plus Composer. Node is only required for MCP Inspector. The home page does not need a frontend build.
`composer.json` pins the Composer platform to PHP 8.3.27, so `composer update` keeps a lock file that installs on both 8.3 and 8.4. Symfony 8 requires PHP 8.4, and this app stays on the Symfony 7 line Laravel 12 also accepts.
```bash
git clone https://github.com/ali-dev5490/laravel_mcp.git
cd laravel_mcp
composer setup
php artisan serve
```
`composer setup` installs dependencies, copies `.env.example` to `.env`, generates `APP_KEY`, creates `database/database.sqlite`, and runs `php artisan migrate --force --seed`.
The same steps by hand:
```bash
composer install
cp .env.example .env
php artisan key:generate
touch database/database.sqlite
php artisan migrate --seed
php artisan serve
```
Open [http://127.0.0.1:8000](http://127.0.0.1:8000). After seeding, the page shows Northline Studio's listing, lead, and order counts.
SQLite is the default. Point `DB_*` at MySQL or Postgres if you want another engine; the migrations use the Laravel schema builder.
Issue an HTTP token (shown once):
```bash
php artisan harbor:token owner@harborboard.test
```
## Claude Desktop
Claude Desktop config lives at `~/Library/Application Support/Claude/claude_desktop_config.json` on macOS and `%APPDATA%\Claude\claude_desktop_config.json` on Windows. Use the absolute path to `artisan`:
```json
{
"mcpServers": {
"harborboard": {
"command": "php",
"args": [
"/absolute/path/to/laravel_mcp/artisan",
"mcp:start",
"harbor"
]
}
}
}
```
Restart Claude Desktop. The server runs as `HARBOR_LOCAL_USER` from `.env`, which defaults to the seeded owner. Ask Claude to search published listings under $700.
## Cursor
This repository includes [`.cursor/mcp.json`](.cursor/mcp.json). Cursor starts the server with the project as the working directory:
```json
{
"mcpServers": {
"harborboard": {
"command": "php",
"args": ["artisan", "mcp:start", "harbor"]
}
}
}
```
For the HTTP transport, run `php artisan serve`, mint a token, and point Cursor at the URL:
```json
{
"mcpServers": {
"harborboard-http": {
"url": "http://127.0.0.1:8000/mcp/harbor",
"headers": {
"Authorization": "Bearer YOUR_SANCTUM_TOKEN"
}
}
}
}
```
## MCP Inspector
Stdio, which is the same command Claude and Cursor run:
```bash
php artisan mcp:inspector harbor
```
Or the Inspector CLI, which connects, lists or calls, and exits:
```bash
npx @modelcontextprotocol/inspector --cli php artisan mcp:start harbor --method tools/list
npx @modelcontextprotocol/inspector --cli php artisan mcp:start harbor \
--method tools/call --tool-name search-listings \
--tool-arg status=published --tool-arg max_price=700
```
HTTP, with the app already serving and a bearer token pasted into the Inspector's header field:
```bash
php artisan serve
php artisan mcp:inspector mcp/harbor
```
A verified stdio listing returns all ten tools. A verified call to `search-listings` with `status=published` and `max_price=700` returns the brass arc lamp (310.00) and the linen lounge chair (620.00), and leaves the oak desk out.
## Example conversation
**You:** Which published pieces are under $700, and who still needs a first reply?
The client calls `search-listings` and `search-leads`. It should name the brass arc lamp and the linen lounge chair, and it should name Chris Patel as a `new` lead. The oak desk is 840.00, so it stays out of the price filter. Maya Ellis is already qualified, so she is not waiting on a first reply.
**You:** Draft a short SMS to Chris about the lounge chair. Then preview an order for Maya's desk. Do not place it.
The client calls `draft-follow-up` with Chris's lead id and `channel=sms`, then `place-order` with Maya's lead id and `confirm` false. The preview looks like this and the database is unchanged:
```json
{
"committed": false,
"requires_confirmation": true,
"message": "No order was written. Show this preview to the user, then call place-order again with confirm=true to commit it.",
"preview": {
"buyer": "Maya Ellis",
"listing": "Oak writing desk",
"amount": "840.00",
"currency": "USD",
"resulting_lead_status": "converted",
"resulting_listing_status": "sold"
},
"order": null
}
```
**You:** Place it.
Only then should the client call `place-order` with `confirm` true. The lead becomes `converted`, the listing becomes `sold`, and a second confirmed call is rejected because the order already exists.
**You:** Read the qualification playbook and tell me whether Elena Rossi is ready to buy the brass lamp.
The client reads `harbor://playbook/qualification` and `get-lead`. Elena is `contacted`, which is not `qualified`, so the answer should be to ask the remaining question rather than to preview an order.
## Security
- Every query is filtered by the signed-in member's `workspace_id`. A miss is reported as not in the caller's workspace, so another tenant's ids are not confirmed.
- Viewers do not receive write tools. Agents do not receive `archive-listing`. Policies repeat those checks inside the handlers.
- `place-order` and `archive-listing` write only when `confirm` is true. Show that preview to a person. The flag is a server-side gate, and a careful host still asks the user before setting it.
- `create-lead` accepts an `idempotency_key`. The same key returns the original lead and ignores the second payload.
- HTTP tokens need the `mcp:use` ability. `php artisan harbor:token` prints the plain token once; Sanctum stores only its hash.
- The `mcp` limiter allows `HARBOR_MCP_RATE_LIMIT` requests per minute (default 60), keyed by user id.
- Laravel MCP checks the `Origin` header on web requests and rejects origins other than the app URL and localhost.
- The stdio server trusts the operating-system user and acts as `HARBOR_LOCAL_USER`. Bind that address to a real member, and keep `mcp:start` on the machine that owns the data.
- The seeded password is a local fixture. Change it, or skip the seeder, before any shared deployment. `.env.example` contains no credentials beyond that published demo password.
## Tests and CI
[Pest](https://pestphp.com) covers the tool catalog by role, search scoping, validation, idempotency, the lead state machine, order preview versus commit, resources, prompts, Sanctum, the token ability, rate limiting, and the token command. [Pint](https://laravel.com/docs/12.x/pint) and [Larastan](https://github.com/larastan/larastan) (PHPStan level 6) run locally and in CI.
```bash
vendor/bin/pint
vendor/bin/phpstan analyse
php artisan test
```
GitHub Actions (`.github/workflows/ci.yml`) runs those three on PHP 8.3 and 8.4 for every push and pull request.
## Docker
Docker is optional. SQLite and `composer setup` are enough for local use.
```bash
docker compose up --build
```
The container listens on port 8000, installs Composer dependencies when `vendor/` is missing, generates `APP_KEY` when it is empty, and migrates and seeds. Re-running the seeder is a no-op once the `northline` workspace exists. Reset with `php artisan migrate:fresh --seed`.
## Project layout
```
app/Mcp/Servers/HarborServer.php Server name, instructions, registration
app/Mcp/Tools Ten tools
app/Mcp/Resources Static resources and URI templates
app/Mcp/Prompts Qualify, follow-up, weekly review
app/Domain Status machine, orders, pipeline
app/Policies Workspace and role checks
routes/ai.php stdio handle and HTTP route
config/harbor.php Local user, demo accounts, rate limit
```
## Roadmap
- OAuth 2.1 with Laravel Passport and `Mcp::oauthRoutes()`, for clients that cannot hold a token you mint yourself
- Cancel and refund an order without leaving the listing sold
- A Livewire desk on top of the same models, so the workspace is usable without an MCP client
- Listing photos as blob resources
- A signed webhook when an order is placed
## License
MIT. See [LICENSE](LICENSE).
## Hire me
Built as a portfolio piece by a senior Laravel engineer (9+ years) who ships Laravel, Vue, and Livewire products and wires them to OpenAI and MCP clients.
- Name: [Your name]
- Upwork: [Your Upwork profile URL]
- Email: [you@example.com]
- GitHub: [your GitHub URL]
This server cannot be deployed
Maintenance
ActivityMaintained
ResponsivenessNo recent community issues