layer1labs
diff --git a/‎src/specsmith/mcp_generator.py‎
Lines changed: 210 additions & 0 deletions b/‎src/specsmith/mcp_generator.py‎
Lines changed: 210 additions & 0 deletions
@@ -0,0 +1,210 @@
+# SPDX-License-Identifier: MIT
+# Copyright (c) 2026 Layer1Labs / BitConcepts, LLC.
+"""MCP Server Generator — auto-scaffold Model Context Protocol servers.
+
+Generates Python MCP servers from natural-language tool descriptions using
+the FastMCP pattern. Each generated server includes a `server.py`,
+`tool_schema.json`, and `README.md`.
+
+Usage:
+    from specsmith.mcp_generator import generate_mcp_server, list_mcp_servers
+    server = generate_mcp_server("Search USPTO patents by keyword")
+"""
+
+from __future__ import annotations
+
+import json
+import re
+import uuid
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Any
+
+
+@dataclass
+class MCPServerSpec:
+    """Specification for a generated MCP server."""
+
+    id: str
+    name: str
+    description: str
+    tools: list[MCPToolSpec] = field(default_factory=list)
+    transport: str = "stdio"  # "stdio" or "http"
+    port: int = 8100
+
+    def to_dict(self) -> dict[str, Any]:
+        return {
+            "id": self.id,
+            "name": self.name,
+            "description": self.description,
+            "tools": [t.to_dict() for t in self.tools],
+            "transport": self.transport,
+            "port": self.port,
+        }
+
+
+@dataclass
+class MCPToolSpec:
+    """Specification for a single MCP tool."""
+
+    name: str
+    description: str
+    input_params: dict[str, str] = field(default_factory=dict)
+    output_type: str = "text"
+
+    def to_dict(self) -> dict[str, Any]:
+        return {
+            "name": self.name,
+            "description": self.description,
+            "input_params": self.input_params,
+            "output_type": self.output_type,
+        }
+
+
+def _generate_server_id(name: str) -> str:
+    slug = re.sub(r"[^a-z0-9]+", "-", name.lower().strip())[:30]
+    return f"mcp-{slug}-{uuid.uuid4().hex[:6]}"
+
+
+def _generate_server_py(spec: MCPServerSpec) -> str:
+    """Generate a Python MCP server file."""
+    tool_funcs = []
+    for tool in spec.tools:
+        params = ", ".join(f"{k}: str" for k in tool.input_params)
+        func = f'''
+@mcp.tool()
+def {tool.name}({params}) -> dict:
+    """{tool.description}"""
+    # TODO: implement actual logic
+    return {{"result": "stub response", "tool": "{tool.name}"}}
+'''
+        tool_funcs.append(func)
+
+    transport_line = (
+        f'    mcp.run(transport="streamable-http", host="127.0.0.1", port={spec.port})'
+        if spec.transport == "http"
+        else '    mcp.run(transport="stdio")'
+    )
+
+    return f'''#!/usr/bin/env python3
+# Auto-generated MCP server: {spec.name}
+# Generated by specsmith mcp generate
+
+from mcp.server.fastmcp import FastMCP
+
+mcp = FastMCP("{spec.name}")
+{"".join(tool_funcs)}
+
+if __name__ == "__main__":
+{transport_line}
+'''
+
+
+def _generate_readme(spec: MCPServerSpec) -> str:
+    """Generate README.md for the MCP server."""
+    tool_list = "\n".join(f"- **{t.name}**: {t.description}" for t in spec.tools)
+    return f"""# {spec.name}
+
+{spec.description}
+
+## Tools
+
+{tool_list}
+
+## Usage
+
+```bash
+# stdio mode
+python server.py
+
+# HTTP mode (if configured)
+python server.py
+```
+
+## Configuration
+
+Add to your MCP client config:
+
+```json
+{{
+  "mcpServers": {{
+    "{spec.id}": {{
+      "command": "python",
+      "args": ["server.py"]
+    }}
+  }}
+}}
+```
+"""
+
+
+def generate_mcp_server(
+    tool_description: str,
+    project_dir: str = ".",
+    transport: str = "stdio",
+    port: int = 8100,
+) -> MCPServerSpec:
+    """Generate an MCP server from a natural-language tool description.
+
+    Creates a server directory with `server.py`, `tool_schema.json`, and `README.md`.
+    """
+    # Parse description into server + tool spec
+    name = tool_description.strip()[:50]
+    server_id = _generate_server_id(name)
+    tool_name = re.sub(r"[^a-z0-9_]+", "_", name.lower().strip())[:40]
+
+    tool = MCPToolSpec(
+        name=tool_name,
+        description=tool_description.strip(),
+        input_params={"query": "Search query or input"},
+    )
+
+    spec = MCPServerSpec(
+        id=server_id,
+        name=name,
+        description=tool_description.strip(),
+        tools=[tool],
+        transport=transport,
+        port=port,
+    )
+
+    # Create server directory
+    server_dir = Path(project_dir).resolve() / ".specsmith" / "mcp-servers" / server_id
+    server_dir.mkdir(parents=True, exist_ok=True)
+
+    # Write files
+    (server_dir / "server.py").write_text(_generate_server_py(spec), encoding="utf-8")
+    (server_dir / "tool_schema.json").write_text(
+        json.dumps(spec.to_dict(), indent=2, ensure_ascii=False), encoding="utf-8"
+    )
+    (server_dir / "README.md").write_text(_generate_readme(spec), encoding="utf-8")
+
+    return spec
+
+
+def list_mcp_servers(project_dir: str = ".") -> list[MCPServerSpec]:
+    """List all generated MCP servers."""
+    servers_dir = Path(project_dir).resolve() / ".specsmith" / "mcp-servers"
+    if not servers_dir.is_dir():
+        return []
+    servers: list[MCPServerSpec] = []
+    for server_dir in sorted(servers_dir.iterdir()):
+        schema_path = server_dir / "tool_schema.json"
+        if schema_path.is_file():
+            try:
+                raw = json.loads(schema_path.read_text(encoding="utf-8"))
+                servers.append(
+                    MCPServerSpec(
+                        id=raw.get("id", ""),
+                        name=raw.get("name", ""),
+                        description=raw.get("description", ""),
+                        transport=raw.get("transport", "stdio"),
+                        port=raw.get("port", 8100),
+                    )
+                )
+            except (OSError, ValueError):
+                continue
+    return servers
+
+
+__all__ = ["MCPServerSpec", "MCPToolSpec", "generate_mcp_server", "list_mcp_servers"]