Build and Deploy a FastMCP Server on macOS Without Writing Code — Let Claude Code Do It

mkdir -p claude-code-fastmcp-server-macos
cd claude-code-fastmcp-server-macos
touch .gitignore

uv init --name macmcp --no-workspace
rm -f main.py hello.py          # remove the sample file uv scaffolds
uv add fastmcp
uv add --dev behave

[project]
name = "macmcp"
version = "0.1.0"
description = "Add your description here"
readme = "README.md"
requires-python = ">=3.12"
dependencies = [
    "fastmcp>=3.4.3",
]

[dependency-groups]
dev = [
    "behave>=1.3.3",
]

touch CLAUDE.md

# CLAUDE.md

Guidance for Claude Code when working in this repository. **The human operator
does not write code by hand** — they describe behavior, run `make`, and review.
Claude Code writes every line of `server.py` and the step definitions.

## What this project is

A FastMCP server (`server.py`) whose behavior is defined by Cucumber/Gherkin
specs in `features/`. The workflow is spec-first: a feature file describes what a
tool does, and Claude Code implements the tool so the spec passes.

## Golden rules

1. **Specs are the source of truth.** Never change a tool's behavior without a
   corresponding scenario in `features/*.feature`. If a request implies new
   behavior, write the scenario first, then the implementation.
2. **The developer only runs `make`.** Every capability must be reachable through
   a Makefile target. Do not tell the human to run raw `python`/`uv`/`behave`
   commands — add or use a target instead.
3. **Use `uv` for everything.** `uv add` for dependencies, `uv run` to execute.
   Never `pip install` or bare `python`.
4. **Keep `server.py` minimal and typed.** One `@mcp.tool` function per behavior,
   with a docstring FastMCP can surface to clients. Preserve the runtime
   transport switch (`MCP_TRANSPORT`).
5. **Always finish green.** After any change, run `make test` and ensure every
   scenario passes before reporting done.

## Tools and agents available

- `/build` — regenerate `server.py` so every scenario in `features/` passes.
- `/add-tool "<description>"` — add a new tool: author a `.feature` scenario and
  the step wiring, then implement it and run the suite.
- Subagent `bdd-author` — turns a plain-English tool description into Gherkin.
- Subagent `mcp-builder` — implements FastMCP tools to satisfy the specs.

## Definition of done

- `make test` passes (all Cucumber scenarios green).
- `make serve` starts the HTTP server without error.
- No hand-written TODOs or placeholders in `server.py`.

mkdir -p features
touch features/tools.feature

Feature: Text tools exposed over MCP
  As an MCP client
  I want to call the server's tools
  So that I can process text through the model context protocol

  Scenario: Count the words in a sentence
    Given a running macmcp server
    When I call "word_count" with text "one two three"
    Then the numeric result is 3

  Scenario: Slugify a title with punctuation
    Given a running macmcp server
    When I call "slugify" with text "Deploy FastMCP on macOS!"
    Then the text result is "deploy-fastmcp-on-macos"

  Scenario: Slugify collapses repeated separators
    Given a running macmcp server
    When I call "slugify" with text "  A  --  B  "
    Then the text result is "a-b"

  Scenario: The server advertises its tools
    Given a running macmcp server
    When I list the available tools
    Then the tool "word_count" is available
    And the tool "slugify" is available

mkdir -p features/steps
touch features/steps/tool_steps.py behave.ini

"""Step definitions for the MCP tool scenarios.

Each step drives the server through FastMCP's in-memory client, so the suite
runs fast and deterministically in CI with no network or subprocess.
"""

import asyncio

from behave import given, then, when
from fastmcp import Client

from server import mcp


def _run(coro):
    """Run an async coroutine from a synchronous behave step."""
    return asyncio.run(coro)


async def _call(tool: str, arguments: dict):
    async with Client(mcp) as client:
        return (await client.call_tool(tool, arguments)).data


async def _tool_names():
    async with Client(mcp) as client:
        return [t.name for t in await client.list_tools()]


@given("a running macmcp server")
def step_server(context):
    context.mcp = mcp


@when('I call "{tool}" with text "{text}"')
def step_call(context, tool, text):
    context.result = _run(_call(tool, {"text": text}))


@when("I list the available tools")
def step_list(context):
    context.tools = _run(_tool_names())


@then("the numeric result is {expected:d}")
def step_numeric(context, expected):
    assert context.result == expected, f"expected {expected}, got {context.result!r}"


@then('the text result is "{expected}"')
def step_text(context, expected):
    assert context.result == expected, f"expected {expected!r}, got {context.result!r}"


@then('the tool "{name}" is available')
def step_available(context, name):
    assert name in context.tools, f"{name!r} not in {context.tools}"

[behave]
show_timings = true
logging_level = WARNING

[behave.userdata]
# The in-memory MCP transport is used by the step definitions; no server URL
# is needed for `make test`.

mkdir -p .claude/agents
touch .claude/agents/bdd-author.md .claude/agents/mcp-builder.md

---
name: bdd-author
description: Turns a plain-English description of an MCP tool into a Cucumber/Gherkin scenario and the matching behave step wiring. Use when adding or changing a tool's behavior.
tools: Read, Write, Edit, Glob, Grep
model: sonnet
---

You author executable specifications for a FastMCP server, in Gherkin.

When given a tool description:

1. Read `features/tools.feature` and `features/steps/tool_steps.py` to match the
   existing style and reuse steps where possible.
2. Add one `Scenario` per observable behavior, including at least one edge case.
   Use the existing step phrasings when they fit:
   - `Given a running macmcp server`
   - `When I call "<tool>" with text "<text>"`
   - `Then the numeric result is <n>` / `Then the text result is "<s>"`
3. Only introduce a new step phrasing if no existing step expresses the check,
   and then add its definition to `features/steps/tool_steps.py`.
4. Keep steps transport-free: they drive the server with FastMCP's in-memory
   `Client(mcp)` so the suite stays fast and deterministic.

Do NOT implement the tool in `server.py` — that is `mcp-builder`'s job. Output
only the specs, then hand off.

---
name: mcp-builder
description: Implements FastMCP tools in server.py so that every Cucumber scenario in features/ passes. Use after the specs exist to write or update the server code.
tools: Read, Write, Edit, Glob, Grep, Bash
model: sonnet
---

You implement a FastMCP server so its behavior matches the Gherkin specs.

Process:

1. Read every `features/*.feature` file and `features/steps/tool_steps.py` to
   learn the required tools, inputs, and expected outputs.
2. Read the current `server.py`. Add or adjust one `@mcp.tool` function per
   required behavior. Each tool must:
   - have typed parameters and return type,
   - carry a one-line docstring FastMCP can advertise,
   - be pure and deterministic where possible.
3. Preserve the transport switch in `main()` (`MCP_TRANSPORT` selecting stdio vs
   http) — never remove it.
4. Run `make test` with Bash and iterate until every scenario is green. Do not
   stop on a red suite.
5. Keep the file minimal: no dead code, no placeholder TODOs.

Report the tools you added/changed and the final `make test` summary.

mkdir -p .claude/commands
touch .claude/commands/build.md .claude/commands/add-tool.md

---
description: Regenerate server.py so every Cucumber scenario in features/ passes
allowed-tools: Read, Write, Edit, Glob, Grep, Bash
---

Bring the server implementation in sync with the specs.

Current scenarios:

!`ls features/*.feature`

Steps:

1. Delegate to the `mcp-builder` subagent to implement or update `server.py` so
   that every scenario in `features/` passes.
2. When it reports back, run `make test` yourself to confirm the suite is green.
3. If anything is red, iterate until it passes. Report the final `make test`
   summary and the list of tools now exposed.

Do not ask the operator to run any commands — do it all and report the result.

---
description: Add a new MCP tool from a plain-English description, spec-first
argument-hint: "<description of the tool>"
allowed-tools: Read, Write, Edit, Glob, Grep, Bash
---

Add a new tool to the server, specification-first. The tool to add:

**$ARGUMENTS**

Steps:

1. Delegate to the `bdd-author` subagent to add Gherkin scenarios for this tool
   to `features/tools.feature` (plus any new step definitions), covering the
   happy path and at least one edge case.
2. Delegate to the `mcp-builder` subagent to implement the tool in `server.py`.
3. Run `make test` and iterate until every scenario passes.
4. Report the scenarios added, the tool signature, and the final test summary.

The operator only described the behavior — you write all the code and specs.

make generate      # runs: claude -p "/build" --permission-mode acceptEdits

"""macmcp — a small FastMCP server.

Generated and maintained by Claude Code from the specs in features/ and
prompts/. You are not expected to edit this file by hand; run `make generate`
to (re)produce it from the behavior specs. Transport is chosen at runtime so
the same file serves local stdio dev and deployed HTTP.
"""

import os

from fastmcp import FastMCP

mcp = FastMCP("macmcp")


@mcp.tool
def word_count(text: str) -> int:
    """Count the whitespace-separated words in a block of text."""
    return len(text.split())


@mcp.tool
def slugify(text: str) -> str:
    """Turn a title into a URL-safe, lowercase slug."""
    cleaned = [c.lower() if c.isalnum() else "-" for c in text.strip()]
    slug = "".join(cleaned)
    while "--" in slug:
        slug = slug.replace("--", "-")
    return slug.strip("-")


def main() -> None:
    if os.environ.get("MCP_TRANSPORT", "stdio").lower() == "http":
        mcp.run(
            transport="http",
            host=os.environ.get("MCP_HOST", "127.0.0.1"),
            port=int(os.environ.get("MCP_PORT", "8000")),
        )
    else:
        mcp.run()


if __name__ == "__main__":
    main()

touch Makefile

.DEFAULT_GOAL := help

# --- Deploy configuration (launchd user agent) --------------------------------
LABEL   := com.macmcp.server
PLIST   := $(HOME)/Library/LaunchAgents/$(LABEL).plist
UV      := $(shell command -v uv)
DIR     := $(shell pwd)
DOMAIN  := gui/$(shell id -u)

# Description passed to `make add-tool DESC="..."`
DESC ?=

.PHONY: help install generate add-tool test serve smoke deploy undeploy status logs ci clean

help:  ## Show this help screen
	@grep -E '^[a-zA-Z_-]+:.*?## .*$$' $(MAKEFILE_LIST) \
		| awk 'BEGIN {FS = ":.*?## "}; {printf "  \033[36m%-10s\033[0m %s\n", $$1, $$2}'

install:  ## Sync runtime and dev dependencies
	uv sync

generate:  ## Have Claude Code (re)write server.py to satisfy the specs
	claude -p "/build" --permission-mode acceptEdits

add-tool:  ## Add a tool from a description: make add-tool DESC="reverse the text"
	@test -n "$(DESC)" || (echo 'Usage: make add-tool DESC="what the tool does"' && exit 1)
	claude -p "/add-tool $(DESC)" --permission-mode acceptEdits

test:  ## Run the Cucumber (behave) suite
	uv run behave

serve:  ## Run the HTTP server in the foreground (Ctrl-C to stop)
	MCP_TRANSPORT=http uv run python server.py

smoke:  ## Call a tool against the running HTTP server
	uv run python scripts/smoke.py

deploy:  ## Render the launchd plist and start the service
	@mkdir -p logs
	@sed -e 's#@UV@#$(UV)#g' \
	     -e 's#@DIR@#$(DIR)#g' \
	     -e 's#@PATH@#$(dir $(UV)):/usr/bin:/bin#g' \
	     deploy/$(LABEL).plist.template > $(PLIST)
	launchctl bootout $(DOMAIN) $(PLIST) 2>/dev/null || true
	launchctl bootstrap $(DOMAIN) $(PLIST)
	@echo "Deployed $(LABEL). Check: make status"

undeploy:  ## Stop the service and remove the launchd plist
	launchctl bootout $(DOMAIN) $(PLIST) 2>/dev/null || true
	rm -f $(PLIST)
	@echo "Removed $(LABEL)."

status:  ## Show whether the service is registered and running
	@launchctl print $(DOMAIN)/$(LABEL) 2>/dev/null \
		| grep -E 'state =|pid =' || echo "$(LABEL) is not loaded."

logs:  ## Tail the service log files
	@tail -n 40 -f logs/server.out.log logs/server.err.log

ci:  ## What CI runs: install then test (no Claude Code required)
	uv sync
	uv run behave

clean:  ## Remove caches and local logs
	rm -rf .pytest_cache logs __pycache__ features/steps/__pycache__

mkdir -p deploy scripts .github/workflows
touch deploy/com.macmcp.server.plist.template scripts/smoke.py .github/workflows/ci.yml

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN"
  "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
    <key>Label</key>
    <string>com.macmcp.server</string>

    <key>ProgramArguments</key>
    <array>
        <string>@UV@</string>
        <string>run</string>
        <string>python</string>
        <string>server.py</string>
    </array>

    <key>WorkingDirectory</key>
    <string>@DIR@</string>

    <key>EnvironmentVariables</key>
    <dict>
        <key>MCP_TRANSPORT</key>
        <string>http</string>
        <key>MCP_HOST</key>
        <string>127.0.0.1</string>
        <key>MCP_PORT</key>
        <string>8000</string>
        <key>PATH</key>
        <string>@PATH@</string>
    </dict>

    <key>RunAtLoad</key>
    <true/>

    <key>KeepAlive</key>
    <true/>

    <key>StandardOutPath</key>
    <string>@DIR@/logs/server.out.log</string>

    <key>StandardErrorPath</key>
    <string>@DIR@/logs/server.err.log</string>
</dict>
</plist>

"""Connect to the running HTTP server and call a tool as a smoke test."""

import asyncio
import os

from fastmcp import Client

URL = os.environ.get("MCP_URL", "http://127.0.0.1:8000/mcp/")


async def main() -> None:
    async with Client(URL) as client:
        print("tools:", [t.name for t in await client.list_tools()])
        result = await client.call_tool("slugify", {"text": "Built by Claude Code"})
        print("slugify ->", result.data)


if __name__ == "__main__":
    asyncio.run(main())

name: CI

on:
  push:
    branches: [main]
  pull_request:

jobs:
  test:
    # The Cucumber suite runs on the committed (Claude-generated) code, so CI is
    # deterministic and needs no Claude Code or API key.
    runs-on: macos-latest
    steps:
      - uses: actions/checkout@v4

      - name: Install uv
        uses: astral-sh/setup-uv@v5

      - name: Run the Cucumber suite
        run: make ci

make generate      # Claude Code writes server.py to satisfy features/
make test

make add-tool DESC="reverse the characters in the text"

make deploy
make status        # state = running, a live pid
make smoke
# tools: ['word_count', 'slugify']
# slugify -> built-by-claude-code
make undeploy