Add MCP Server for Agent Discovery

[Dimwiddle]

SpecLeft MCP Server — Design Specification (v0.3)

Goal

Add a new SpecLeft feature to accommodate MCP server for optimised agent utilisation and discovery.

Acceptance criteria

• an MCP server is created with 3 resources and 1 tool
• the MCP specleft feature (feature-id: 'feature-mcp-server', priority: high) has been added in to features/ with end-to-end scenarios to cover the resources and tool calls.
• unit, integration, security and token usage test coverage
• Entry point for mcp server is python -m specleft.mcp

Architecture

SpecLeft's MCP surface is intentionally minimal. The server exposes 3 resources for context and 1 tool for project setup. All other CLI capabilities are delegated to the agent's native shell execution via a skill file generated during init.

Include ./src/mcp in to the current project.

MCP Server (always in context)
├── specleft://contract     → safety guarantees
├── specleft://guide        → workflow + spec format
├── specleft://status       → project state + coverage
└── specleft_init           → project setup + skill file generation

Skill file (read once from disk)
└── .specleft/SKILL.md → full CLI command reference

Rationale: Target agents (Claude Code, Cursor, Aider) already have native shell execution. Wrapping every CLI command as an MCP tool adds ~180 tokens per turn in declarations with no functional benefit over specleft <command> --format json. The skill file teaches workflow and sequencing more effectively than tool descriptions can, at zero per-turn cost.

Testing

Test the SpecLeft MCP server (3 resources + 1 tool) using FastMCP’s in-memory Client for automated tests and MCP Inspector for manual debugging.

Test location: tests/mcp/

Test strategy: Details in comments

Dependencies

[project.optional-dependencies]
mcp = ["fastmcp<3"]
dev = [
    # ... existing dev deps ...
    "pytest-asyncio",
    "tiktoken",
]

---

Server Metadata

{
  "$schema": "https://static.modelcontextprotocol.io/schemas/2025-12-11/server.schema.json",
  "name": "io.github.SpecLeft/specleft",
  "title": "SpecLeft",
  "description": "Track and enforce Python feature coverage with verifiable safety guarantees. Generates pytest test scaffolding from markdown specifications, monitors implementation progress, and blocks PRs that violate coverage policies. Agent-optimised: 3 resources, 1 tool, offline-only, no telemetry, no API keys required.",
  "version": "0.3.0",
  "websiteUrl": "https://specleft.dev",
  "repository": {
    "url": "https://github.com/SpecLeft/specleft",
    "source": "github"
  },
  "packages": [
    {
      "registryType": "pypi",
      "registryBaseUrl": "https://pypi.org",
      "identifier": "specleft",
      "version": "0.3.0",
      "runtimeHint": "uvx",
      "transport": {
        "type": "stdio"
      },
      "packageArguments": [
        {
          "type": "positional",
          "value": "mcp"
        }
      ],
      "environmentVariables": []
    }
  ]
}

Registry tags: testing, python, pytest, specifications, tdd, bdd, code-quality

---

Resources

Important: Payload shapes demonstrate the shape only, not the actual output. No functional change to the output is expected - unless stated otherwise.

specleft://contract

Field	Value
URI	specleft://contract
Name	SpecLeft Agent Contract
Parameter	pretty: bool (default: false)
MIME type	application/json
Description	Safety and determinism guarantees for this SpecLeft installation. Read before invoking any tools or CLI commands. Defines what is safe to retry, what never writes without confirmation, and exit code semantics.

When agents should read this: Before first interaction. Establishes trust boundary.

Payload shape:

{
  "contract_version": "1.0",
  "specleft_version": "0.3.0",
  "guarantees": {
    "safety": {
      "no_implicit_writes": true,
      "dry_run_never_writes": true,
      "existing_tests_not_modified_by_default": true
    },
    "execution": {
      "skeletons_skipped_by_default": true,
      "skipped_never_fail": true,
      "validation_non_destructive": true
    },
    "determinism": {
      "deterministic_for_same_inputs": true,
      "safe_for_retries": true
    },
    "cli_api": {
      "json_supported_globally": true,
      "json_additive_within_minor": true,
      "exit_codes": {
        "success": 0,
        "error": 1,
        "cancelled": 2
      }
    },
    "skill_security": {
      "skill_file_integrity_check": true,
      "skill_file_commands_are_simple": true
    },
    "exit_codes": { "success": 0, "error": 1, "cancelled": 2 },
  }
}

Target size: ~80 tokens

---

specleft://guide

Field	Value
URI	specleft://guide
Name	SpecLeft Workflow Guide
MIME type	application/json
Parameter	pretty: bool (default: false)
Description	How to use SpecLeft: workflow sequence, canonical feature template, spec format rules, and scenario structure. Read once before creating or modifying feature specs. For full CLI command reference, read .specleft/SKILL.md after running init.

When agents should read this: Before creating any feature specs or generating tests.

Expected Payload:

{
  "workflow": {
    "bulk_setup": [
      {"step": 1, "command": "plan --analyze", "description": "Understand how the current plan aligns with the prd-template.yml"},
      {"step": 2, "action": "modify", "description": "If required - modify the .specleft/prd-template.yml to fully align PRD"},
      {"step": 3, "command": "plan", "description": "Generate features from calibrated PRD"},
      {"step": 4, "command": "features add-scenario --add-test skeleton", "description": "Add scenarios with test scaffolding"}
    ],
    "incremental_setup": [
      {"step": 1, "command": "features add", "description": "Add individual feature"},
      {"step": 2, "command": "features add-scenario --add-test skeleton", "description": "Add scenarios with test scaffolding"}
    ],
    "implementation": [
      {"step": 1, "command": "next --limit 1", "description": "Pick next scenario to implement"},
      {"step": 2, "action": "implement", "description": "Write test logic first, followed by application code"},
      {"step": 3, "action": "pytest", "description": "Run test, fix if failing, repeat from step 1"},
      {"step": 4, "command": "features validate --strict", "description": "Validate all specs before commit"},
      {"step": 5, "command": "coverage --threshold 100", "description": "Verify full feature coverage"}
    ]
  },
  "skill_file": "Run specleft_init to generate .specleft/SKILL.md with full CLI reference"
}

Target size: ~220 tokens

---

specleft://status

Field	Value
URI	specleft://status
Name	SpecLeft Project Status
MIME type	application/json
Arguments	verbose (default: false) , pretty (default: false)
Description	Current project state: feature list, scenario counts, implementation coverage, and priority breakdown. Summary-first — use CLI commands for scenario-level detail. Returns empty features array if project is not initialised.

When agents should read this: Before planning work. Periodically during implementation to track progress.

Default Payload shape (Verbose = False):

{"initialised": true, "features":3,"scenarios":12,"implemented":7,"skipped":5,"coverage_percent":58.3}

**Note: ** "initialised": true has to be added to the current status payload. Then re-use that function for the output (same as CLI command)
Payload shape (Verbose = True):

{
  "initialised": true,
  "summary": {
    "features": 12,
    "scenarios": 48,
    "implemented": 31,
    "skipped": 17,
    "coverage_percent": 64.6
  },
  "by_priority": {
    "critical": { "total": 5, "implemented": 5, "percent": 100.0 },
    "high": { "total": 12, "implemented": 8, "percent": 66.7 },
    "medium": { "total": 25, "implemented": 15, "percent": 60.0 },
    "low": { "total": 6, "implemented": 3, "percent": 50.0 }
  },
  "features": [
    {
      "feature_id": "auth",
      "scenarios": 6,
      "implemented": 6,
      "coverage_percent": 100.0
    },
    {
      "feature_id": "payments",
      "scenarios": 8,
      "implemented": 3,
      "coverage_percent": 37.5
    }
  ]
}

Scaling behaviour: Summary is fixed ~30 tokens. Each feature entry is ~15 tokens. A 20-feature project costs ~330 tokens. Scenario-level detail is never inlined — agents drill down via specleft next --feature <id> --format json in the shell.

Uninitialised project response:

{
  "initialised": false,
  "summary": { "features": 0, "scenarios": 0, "implemented": 0, "skipped": 0, "coverage_percent": 0 },
  "by_priority": {},
  "features": []
}

This signals the agent to call specleft_init before proceeding.

---

Tools

specleft_init

Field	Value
Name	specleft_init
Description	Initialise SpecLeft project: creates directory structure (features/, tests/, .specleft/), runs environment health checks, and generates .specleft/SKILL.md with full CLI command reference. Call this first if specleft://status shows initialised=false.

Input schema:

{
  "type": "object",
  "properties": {
    "example": {
      "type": "boolean",
      "default": false,
      "description": "Create example feature specs to demonstrate format"
    },
    "blank": {
      "type": "boolean",
      "default": false,
      "description": "Create empty directory structure only"
    },
    "dry_run": {
      "type": "boolean",
      "default": false,
      "description": "Show what would be created without writing"
    }
  }
}

Output shape:

{
  "success": true,
  "health": {
    "python_version": "3.11.0",
    "dependencies_ok": true,
    "plugin_registered": true
  },
  "created": [
    ".specleft/specs",
    ".specleft/policies",
    ".specleft/",
    ".specleft/SKILL.md"
  ],
  "skill_file": ".specleft/SKILL.md",
  "next_steps": "Read .specleft/SKILL.md for full CLI reference"
}

Health check integration: Init runs specleft doctor checks internally. If the environment is unhealthy, init fails with diagnostic output rather than creating a broken project. No separate doctor resource needed.

Idempotent: Safe to re-run. Existing directories and files are preserved. Skill file is regenerated to reflect current CLI version.

---

Add the following snippet to the README.md

## MCP Server Setup

SpecLeft includes an MCP server that connects directly to AI coding agents like Claude Code, Cursor, Codex, OpenCode etc. Once connected, your agent can read specs, track coverage, and generate test scaffolding without leaving the conversation.

See [GET_STARTED.md](https://github.com/SpecLeft/specleft/blob/main/GET_STARTED.md) for details

---

Add the following snippet to the GET_STARTED.md

## MCP Server Setup

SpecLeft includes an MCP server that connects directly to AI coding agents like Claude Code, Cursor, and Windsurf. Once connected, your agent can read specs, track coverage, and generate test scaffolding without leaving the conversation.

### Prerequisites

- Python 3.10+
- SpecLeft installed (`pip install specleft[mcp]`)

### Option 1: uvx (recommended)

If you have [uv](https://docs.astral.sh/uv/getting-started/installation/) installed, this is the fastest path. No separate install step — the MCP client handles everything.

**Claude Code** (`.claude/settings.json`):
```json
{
  "mcpServers": {
    "specleft": {
      "command": "uvx",
      "args": ["specleft", "mcp"]
    }
  }
}

Cursor (.cursor/mcp.json):

{
  "mcpServers": {
    "specleft": {
      "command": "uvx",
      "args": ["specleft", "mcp"]
    }
  }
}

Option 2: pip install

If you don't have uv, install SpecLeft first, then point your MCP client at the CLI directly.

pip install specleft[mcp]

Claude Code (.claude/settings.json):

{
  "mcpServers": {
    "specleft": {
      "command": "specleft",
      "args": ["mcp"]
    }
  }
}

Cursor (.cursor/mcp.json):

{
  "mcpServers": {
    "specleft": {
      "command": "specleft",
      "args": ["mcp"]
    }
  }
}

Verify the connection

Once configured, restart your editor. You should see SpecLeft listed as a connected MCP server with 3 resources and 1 tool. If the connection fails, run the health check:

specleft doctor

This checks Python version, dependencies, and plugin registration. Fix any issues it reports, then restart your editor to reconnect.

---


## CLI → MCP Classification Reference

Complete mapping of all CLI commands to their MCP role.

### Exposed via MCP (always in context)

| CLI Command | MCP Type | MCP Identifier |
|---|---|---|
| `specleft contract` | Resource | `specleft://contract` |
| N/A | Resource | `specleft://guide` |
| `specleft status` + `coverage` + `features list` + `features stats` | Resource (merged) | `specleft://status` |
| `specleft init` + `doctor` | Tool (merged) | `specleft_init` |

### Delegated to skill file (zero per-turn cost)

| CLI Command | Skill file section | Mutation |
|---|---|---|
| `specleft features validate` | Features | Read-only |
| `specleft features add` | Features | Write (creates file) |
| `specleft features add-scenario` | Features | Write (appends to file) |
| `specleft next` | Status & Planning | Read-only |
| `specleft test skeleton` | Test Generation | Write (creates files) |
| `specleft test stub` | Test Generation | Write (creates files) |
| `specleft test report` | Test Generation | Write (creates HTML) |
| `specleft skill status` | Skill Integrity | Read-only |
| `specleft plan` | Planning | Write (creates feature files) |
| `specleft contract test` | Contract | Read-only (isolated temp dir) |
| `specleft enforce` | Enforcement | Read-only |
| `specleft license status` | License | Read-only |
| `specleft guide` | Status & Planning | Read-only |

---

## Agent Discovery Flow

1. Agent connects to MCP server
2. Sees 3 resources + 1 tool (minimal surface)
3. Reads specleft://contract → understands safety model
4. Reads specleft://guide → understands workflow
5. Reads specleft://status → understands project state
6. If initialised=false → calls specleft_init
7. Reads .specleft/SKILL.md → has full CLI reference (19 commands)
8. Works using shell commands with --format json

Steps 3–5 happen naturally based on resource descriptions. Step 6 is triggered by the status response. Step 7 is prompted by both the guide payload and init output.

---

## Token Budget

### Per-turn overhead (every turn of conversation)

| Component | Tokens | Notes |
|---|---|---|
| Resource declarations (×3) | ~60 | URI + name + description each |
| Tool declaration (×1) | ~25 | Name + description + input schema |
| **Total per turn** | **~85** | |
| **30-turn session** | **~2,550** | |

### One-time costs (read once per session)

| Component | Tokens | Notes |
|---|---|---|
| Contract payload | ~80 | Read at session start |
| Guide payload | ~500 | Read at session start |
| Status payload | ~200 | Read at start + periodically (12-feature project) |
| Skill file | ~800 | Read from disk after init |
| **Total one-time** | **~1,580** | |

### Session total

**30-turn session: ~4,130 tokens**

Compared to wrapping all 19 commands as MCP tools (~15,000+ tokens), this is a **72% reduction**.

### Net-positive threshold

One avoided wrong-path-then-correction cycle costs 2,000–5,000 tokens. SpecLeft's MCP presence pays for itself if it prevents a **single** misstep per session. At ~4,130 tokens total overhead, the margin is wide.

[Dimwiddle]

MCP Server Testing Strategy

Overview

Test the SpecLeft MCP server (3 resources + 1 tool) using FastMCP’s in-memory Client for automated tests and MCP Inspector for manual debugging.

Test location: tests/mcp/

---

Layer 1: Unit Tests — Resource & Tool Logic

Test resource handlers and tool logic as pure functions, decoupled from MCP transport. These validate correctness of payloads independent of the protocol.

Scope:

• contract() returns all documented guarantee keys with correct types
• guide() returns json payload containing the specleft workflow
• status() returns initialised=false for empty directories, accurate counts for real projects
• specleft_init() handler creates expected files, respects dry_run, is idempotent

These run in milliseconds and catch most regressions.

---

Layer 2: Protocol & Integration — FastMCP In-Memory Client

Use FastMCP’s Client(mcp) in-memory transport to test through the real MCP protocol surface without subprocess management or stdio framing.

Resource Tests

@pytest.mark.asyncio
async def test_lists_exactly_three_resources(client):
    async with client:
        resources = await client.list_resources()
        uris = {r.uri for r in resources}
        assert uris == {
            "specleft://contract",
            "specleft://guide",
            "specleft://status",
        }

@pytest.mark.asyncio
async def test_contract_resource_shape(client):
    async with client:
        result = await client.read_resource("specleft://contract")
        payload = json.loads(result[0].text)
        assert payload["contract_version"] == "1.0"
        required = {
            "dry_run_never_writes", "no_writes_without_confirmation",
            "existing_files_never_overwritten", "skeletons_skipped_by_default",
            "skipped_never_fail", "deterministic_for_same_inputs",
            "safe_for_retries", "exit_codes",
        }
        assert required.issubset(payload["guarantees"].keys())

@pytest.mark.asyncio
async def test_status_uninitialised(client, tmp_path, monkeypatch):
    monkeypatch.chdir(tmp_path)
    async with client:
        result = await client.read_resource("specleft://status")
        payload = json.loads(result[0].text)
        assert payload["initialised"] is False
        assert payload["features"] == []

Tool Tests

@pytest.mark.asyncio
async def test_lists_exactly_one_tool(client):
    async with client:
        tools = await client.list_tools()
        assert len(tools) == 1
        assert tools[0].name == "specleft_init"

@pytest.mark.asyncio
async def test_init_creates_project(client, tmp_path, monkeypatch):
    monkeypatch.chdir(tmp_path)
    async with client:
        result = await client.call_tool("specleft_init", {"example": True})
        payload = json.loads(result[0].text)
        assert payload["success"] is True
        assert (tmp_path / "features").is_dir()
        assert (tmp_path / ".specleft" / "specleft_skill.md").exists()

@pytest.mark.asyncio
async def test_init_dry_run_writes_nothing(client, tmp_path, monkeypatch):
    monkeypatch.chdir(tmp_path)
    before = set(tmp_path.rglob("*"))
    async with client:
        await client.call_tool("specleft_init", {"dry_run": True})
    after = set(tmp_path.rglob("*"))
    assert before == after

@pytest.mark.asyncio
async def test_init_is_idempotent(client, tmp_path, monkeypatch):
    monkeypatch.chdir(tmp_path)
    async with client:
        r1 = await client.call_tool("specleft_init", {"blank": True})
        r2 = await client.call_tool("specleft_init", {"blank": True})
        assert json.loads(r1[0].text)["success"] is True
        assert json.loads(r2[0].text)["success"] is True

Status with Real Project State

@pytest.mark.asyncio
async def test_status_reflects_real_coverage(client, sample_project, monkeypatch):
    monkeypatch.chdir(sample_project)
    async with client:
        result = await client.read_resource("specleft://status")
        payload = json.loads(result[0].text)
        assert payload["initialised"] is True
        assert payload["summary"]["features"] > 0
        assert 0 <= payload["summary"]["coverage_percent"] <= 100

---

Layer 3: Security Tests

Verify contract-level security guarantees from the MCP spec.

Required checks:

• Init refuses to write through symlinks (raises SecurityError)
• Init refuses path traversal outside project directory
• Skill file checksum matches after generation (specleft_skill.md.sha256)
• Skill file contains no shell metacharacters (|, ;, &, $, backticks) in command lines
• Skill file permissions are read-only (444)

def test_init_refuses_symlink(tmp_path, monkeypatch):
    monkeypatch.chdir(tmp_path)
    target = tmp_path.parent / "outside"
    target.mkdir()
    (tmp_path / "features").symlink_to(target)
    with pytest.raises(SecurityError, match="symlink"):
        specleft_init_handler({"blank": True})

def test_skill_file_integrity(tmp_path, monkeypatch):
    monkeypatch.chdir(tmp_path)
    specleft_init_handler({"blank": True})
    import hashlib
    skill = (tmp_path / ".specleft" / "specleft_skill.md").read_bytes()
    expected = (tmp_path / ".specleft" / "specleft_skill.md.sha256").read_text().strip()
    assert hashlib.sha256(skill).hexdigest() == expected

def test_skill_file_no_shell_metacharacters(tmp_path, monkeypatch):
    monkeypatch.chdir(tmp_path)
    specleft_init_handler({"blank": True})
    content = (tmp_path / ".specleft" / "specleft_skill.md").read_text()
    import re
    commands = [l.strip() for l in content.splitlines() if l.strip().startswith("specleft ")]
    for cmd in commands:
        assert not re.search(r'[|;&>`$()]', cmd), f"Metacharacter in: {cmd}"

---

Layer 4: Token Budget Tests

Protect the token targets defined in the MCP spec. Flags scope creep on payload sizes.

def test_contract_under_100_tokens():
    payload = json.dumps(contract_resource(), separators=(',', ':'))
    assert count_tokens(payload) <= 100

def test_guide_under_300_tokens():
    assert count_tokens(guide_resource()) <= 300

def test_declarations_under_120_tokens():
    # Resource list + tool list total overhead
    ...

Use tiktoken with cl100k_base encoding for approximate counts.

---

Layer 5: Agent Discovery Flow (End-to-End)

Single test simulating the documented 8-step agent discovery sequence.

@specleft(feature_id={feature-id}, scenario_id={scenario-id})
@pytest.mark.asyncio
async def test_full_agent_discovery_flow(client, tmp_path, monkeypatch):
    monkeypatch.chdir(tmp_path)
    async with client:
        # 1. Read contract — establish trust
        contract = await client.read_resource("specleft://contract")
        assert "guarantees" in json.loads(contract[0].text)

        # 2. Read guide — understand workflow
        guide = await client.read_resource("specleft://guide")
        assert "## Workflow" in guide[0].text

        # 3. Read status — uninitialised
        status = await client.read_resource("specleft://status")
        assert json.loads(status[0].text)["initialised"] is False

        # 4. Call init
        init = await client.call_tool("specleft_init", {"example": True})
        assert json.loads(init[0].text)["success"] is True

        # 5. Status now reflects project
        status = await client.read_resource("specleft://status")
        assert json.loads(status[0].text)["initialised"] is True

        # 6. Skill file exists and is valid
        skill = (tmp_path / ".specleft" / "specleft_skill.md")
        assert skill.exists()
        assert "specleft next" in skill.read_text()

---

Manual Testing (Development Only)

Note: Agent ignore - remind owner to carry out this testing

Use MCP Inspector for interactive debugging during development. Not for CI.

npx @modelcontextprotocol/inspector python -m specleft.mcp_server

Verify: resources load, tool executes, payloads render correctly.

---

Priority

Layer	Effort	Value	CI
1. Unit tests	Low	High	Yes
2. In-memory client	Medium	High	Yes
3. Security	Medium	High	Yes
4. Token budget	Low	Medium	Yes
5. Discovery flow	Low	High	Yes
Manual Inspector	Low	Medium	No

[Dimwiddle]

Implementation Notes

Branch: 76-add-mcp-server-discovery
Approach: Implemented a minimal FastMCP server surface with 3 resources + 1 init tool, backed by existing SpecLeft command payloads.

Decisions

• Keep MCP resources thin and reuse existing command payload generators where possible to avoid output drift.
• Keep token-budget tests deterministic in offline environments by skipping only when cl100k_base cannot be loaded.

Tasks

• Add FastMCP server package with 3 resources and 1 tool plus python -m entrypoint
• Integrate MCP command in CLI and package dependencies (mcp extra)
• Implement MCP payload plumbing for contract, guide, and status (with initialised true/false)
• Add feature spec for MCP server scenarios in features/
• Add MCP tests (unit, integration, security, token usage)
• Update docs (README + GET_STARTED) and verify lint/tests