[Feature] Publish SpecLeft to MCP Registry

[Dimwiddle]

Summary

Publish SpecLeft's MCP server to the official Anthropic MCP Registry and automate future releases via CI/CD. This enables one-click installation in Claude Desktop and automatic discovery by MCP-compatible agents.

Target release: v0.3.0 (after MCP server implementation)

Depends On

• Add MCP Server for Agent Discovery #76 — MCP Server Implementation (must be merged first)

Tasks

1. End-to-End Testing Flow

Verify the SpecLeft MCP server works as a real installed package over stdio transport — catching deployment bugs that in-memory client tests cannot: missing wheel dependencies, broken entry points, import-time errors, and malformed stdio framing.

Entry point: python -m specleft.mcp Minimum Python: 3.9

Testing details in the comments.

2. Registry Manifest

• Create server.json in repository root:

{
  "$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": []
    }
  ]
}

3. Initial Publication

• Install mcp-publisher CLI locally
• Authenticate with GitHub OAuth (mcp-publisher login)
• Verify listing at https://registry.modelcontextprotocol.io/v0/servers
• Test one-click install in Claude Desktop

4. CI/CD Automation

• Trigger: release published
• Steps: install mcp-publisher → publish to registry
• Authentication: GitHub OIDC (no secrets required)
• Test workflow with a pre-release tag by running E2E test in CI

5. Documentation Updates

[![MCP Registry](https://img.shields.io/badge/MCP-Registry-blue)](https://registry.modelcontextprotocol.io/servers/io.github.specleft/specleft)

• Add Claude Desktop installation instructions to docs/mcp.md (created in Add MCP Server for Agent Discovery #76)

Success Criteria

• Server listed in official MCP Registry
• E2E Test in CI and local Makefile
• Claude Desktop can discover and install SpecLeft via registry
• CI/CD workflow auto-publishes on new releases
• Badge renders correctly in README

Notes

• MCP Registry is self-service — no approval process required
• Publishing is immediate and zero-cost
• Downstream registries (GitHub Marketplace, etc.) auto-sync from the official registry
• server.json uses schema version 2025-12-11 (latest stable)
• Registry API is v0.1 (frozen, stable for 30+ days)

References

• MCP Registry Documentation
• MCP Publishing Guide
• Server.json Reference

[Dimwiddle]

MCP Server E2E Testing Strategy

Goal

Verify the SpecLeft MCP server works as a real installed package over stdio transport — catching deployment bugs that in-memory client tests cannot: missing wheel dependencies, broken entry points, import-time errors, and malformed stdio framing.

Entry point: python -m specleft.mcp Minimum Python: 3.9

---

CI: Installed Package over Stdio

Runs on PRs. Builds the wheel, installs it in a clean container, and verifies the MCP server responds correctly over stdio.

# .github/workflows/test-mcp-e2e.yml
name: MCP E2E
on:

pull_request:

paths:

- "src/specleft/mcp/**"

- "src/specleft/mcp.py"

- "pyproject.toml"
jobs:

e2e:

runs-on: ubuntu-latest

strategy:

matrix:

python-version: ["3.9", "3.10", "3.11", "3.12"]

container:

image: python:${{ matrix.python-version }}-slim

steps:

- uses: actions/checkout@v4
  - name: Build and install wheel
    run: |
      pip install build
      python -m build
      pip install dist/*.whl

  - name: Verify MCP server starts and responds
    run: python tests/mcp/e2e_stdio.py

Stdio Smoke Test Script

# tests/mcp/e2e_stdio.py
"""
E2E test: verify MCP server responds over stdio transport.
Runs against the installed package, not source.

No pytest dependency — runs standalone.

"""

import json

import subprocess

import sys

import time
def send_jsonrpc(proc, method, params=None, msg_id=1):

"""Send a JSON-RPC message and return raw stdout bytes."""

request = {"jsonrpc": "2.0", "method": method, "id": msg_id}

if params:

request["params"] = params

body = json.dumps(request)

header = f"Content-Length: {len(body)}\r\n\r\n"

proc.stdin.write(header.encode() + body.encode())

proc.stdin.flush()
def read_response(proc, timeout=5):

"""Read one content-length-framed response."""

import select
output = b""
deadline = time.monotonic() + timeout
while time.monotonic() < deadline:
    ready, _, _ = select.select([proc.stdout], [], [], 0.1)
    if ready:
        chunk = proc.stdout.read1(4096)
        if chunk:
            output += chunk
            # Check if we have a complete message
            if b"\r\n\r\n" in output:
                header, _, body_start = output.partition(b"\r\n\r\n")
                for line in header.split(b"\r\n"):
                    if line.lower().startswith(b"content-length:"):
                        length = int(line.split(b":")[1].strip())
                        if len(body_start) >= length:
                            return json.loads(body_start[:length])
return None

def main():

proc = subprocess.Popen(

[sys.executable, "-m", "specleft.mcp"],

stdin=subprocess.PIPE,

stdout=subprocess.PIPE,

stderr=subprocess.PIPE,

)
failures = []

try:
    # 1. Initialize handshake
    send_jsonrpc(proc, "initialize", {
        "protocolVersion": "2024-11-05",
        "capabilities": {},
        "clientInfo": {"name": "e2e-test", "version": "1.0"},
    })
    response = read_response(proc)
    if not response or "result" not in response:
        failures.append(f"Initialize failed: {response}")
    elif response["result"]["serverInfo"]["name"] != "specleft":
        failures.append(f"Wrong server name: {response['result']['serverInfo']}")
    else:
        print("✓ Initialize handshake")

    # 2. Send initialized notification
    notify = {"jsonrpc": "2.0", "method": "notifications/initialized"}
    body = json.dumps(notify)
    header = f"Content-Length: {len(body)}\r\n\r\n"
    proc.stdin.write(header.encode() + body.encode())
    proc.stdin.flush()

    # 3. List resources — expect exactly 3
    send_jsonrpc(proc, "resources/list", msg_id=2)
    response = read_response(proc)
    if not response or "result" not in response:
        failures.append(f"resources/list failed: {response}")
    else:
        uris = {r["uri"] for r in response["result"]["resources"]}
        expected = {"specleft://contract", "specleft://guide", "specleft://status"}
        if uris != expected:
            failures.append(f"Wrong resources: {uris} (expected {expected})")
        else:
            print("✓ Resources list (3 resources)")

    # 4. List tools — expect exactly 1
    send_jsonrpc(proc, "tools/list", msg_id=3)
    response = read_response(proc)
    if not response or "result" not in response:
        failures.append(f"tools/list failed: {response}")
    else:
        tools = response["result"]["tools"]
        if len(tools) != 1 or tools[0]["name"] != "specleft_init":
            failures.append(f"Wrong tools: {tools}")
        else:
            print("✓ Tools list (1 tool: specleft_init)")

    # 5. Read contract resource
    send_jsonrpc(proc, "resources/read", {
        "uri": "specleft://contract"
    }, msg_id=4)
    response = read_response(proc)
    if not response or "result" not in response:
        failures.append(f"Contract read failed: {response}")
    else:
        content = response["result"]["contents"][0]["text"]
        payload = json.loads(content)
        if "guarantees" not in payload:
            failures.append(f"Contract missing guarantees: {payload}")
        else:
            print("✓ Contract resource readable")

finally:
    proc.terminate()
    proc.wait(timeout=5)

# Report
if failures:
    print(f"\n✗ {len(failures)} failure(s):")
    for f in failures:
        print(f"  - {f}")
    sys.exit(1)
else:
    print(f"\n✓ All E2E checks passed")
    sys.exit(0)

if name == "main":

main()

---

Local: Smoke Test via Makefile

For quick local verification before pushing. Builds a clean container, installs the wheel, and runs the same stdio test.

Dockerfile

# test-mcp.Dockerfile
FROM python:3.11-slim
WORKDIR /app
COPY dist/*.whl .

RUN pip install --no-cache-dir *.whl
Verify clean import before stdio test
RUN python -c "import specleft.mcp; print('MCP module imports OK')"
COPY tests/mcp/e2e_stdio.py /app/e2e_stdio.py
ENTRYPOINT ["python", "/app/e2e_stdio.py"]

Makefile

.PHONY: test-mcp-e2e
test-mcp-e2e: ## Run MCP E2E smoke test in a clean container

python -m build

docker build -f test-mcp.Dockerfile -t specleft-mcp-e2e .

docker run --rm specleft-mcp-e2e

make test-mcp-e2e

---

What This Catches (vs In-Memory Tests)

Bug class	In-memory client	E2E stdio
Logic errors in resource/tool handlers	✓	✓
Missing dependency in wheel	✗	✓
Broken python -m specleft.mcp entry point	✗	✓
Import-time errors in installed package	✗	✓
Malformed stdio content-length framing	✗	✓
Server metadata (name, version) incorrect	✗	✓
Python version compatibility (3.9–3.12)	Partial	✓

---

Acceptance Criteria

• tests/mcp/e2e_stdio.py runs standalone (no pytest dependency)
• CI job runs on PRs touching MCP source or pyproject.toml
• CI tests against Python 3.9, 3.10, 3.11, 3.12
• Tests verify: initialize handshake, 3 resources, 1 tool, contract readable
• make test-mcp-e2e runs locally with a single command
• Exit code 0 on success, 1 on any failure

[Dimwiddle]

Implementation Notes Update (MCP E2E)

Completed the MCP end-to-end testing slice in this branch:

• Added standalone stdio E2E smoke test: tests/mcp/e2e_stdio.py
• Added CI workflow: .github/workflows/test-mcp-e2e.yml
• Added local container runner: test-mcp.Dockerfile
• Added one-command local target: make test-mcp-e2e

Validated locally:

• python tests/mcp/e2e_stdio.py passes (initialize, 3 resources, 1 tool, contract read)
• Existing MCP integration/security tests pass (pytest tests/mcp/test_server.py tests/mcp/test_security.py -q)

Notes:

• This server currently uses newline-delimited JSON-RPC over stdio in practice, so the E2E script validates that transport behavior.
• CI matrix is set to Python 3.10/3.11/3.12 to match pyproject.toml (requires-python = >=3.10).

[Dimwiddle]

Follow-up update:

• Added MCP testing doc: docs/mcp-testing.md
• Updated README MCP section to link to docs/mcp-testing.md
• Added MCP Registry badge to README:
  [![MCP Registry](https://img.shields.io/badge/MCP-Registry-blue)](https://registry.modelcontextprotocol.io/servers/io.github.specleft/specleft)