katalyst-taxonomy-mcp 2.4.0__tar.gz

katalyst_taxonomy_mcp-2.4.0/.gitignore

@@ -0,0 +1,105 @@
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[cod]
+*$py.class
+
+# C extensions
+*.so
+
+# Distribution / packaging
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+
+# PyInstaller
+*.manifest
+*.spec
+
+# Installer logs
+pip-log.txt
+pip-delete-this-directory.txt
+
+# Unit test / coverage reports
+htmlcov/
+.tox/
+.nox/
+.coverage
+.coverage.*
+.cache
+nosetests.xml
+coverage.xml
+*.cover
+*.py,cover
+.hypothesis/
+.pytest_cache/
+
+# Translations
+*.mo
+*.pot
+
+# Environments
+.env
+.venv
+env/
+venv/
+ENV/
+env.bak/
+venv.bak/
+
+# Spyder project settings
+.spyderproject
+.spyproject
+
+# Rope project settings
+.ropeproject
+
+# mkdocs documentation
+/site
+
+# mypy / pyright
+.mypy_cache/
+.dmypy.json
+dmypy.json
+.pyright/
+
+# Ruff
+.ruff_cache/
+
+# IDE
+.idea/
+.vscode/
+*.swp
+*.swo
+*~
+
+# OS
+.DS_Store
+Thumbs.db
+
+# Local configuration
+*.local
+
+# Browser/Playwright state files
+browser-state-*.json
+
+# Build artifacts
+site/
+stack-tests/cucumber-report/
+stack-tests/test-results/
+
+# Generated artifacts (rebuild with `just generate-schemas`)
+taxonomy/src/katalyst_taxonomy/engine/generated/
+.worktrees/

katalyst_taxonomy_mcp-2.4.0/PKG-INFO

@@ -0,0 +1,14 @@
+Metadata-Version: 2.4
+Name: katalyst-taxonomy-mcp
+Version: 2.4.0
+Summary: MCP server and REST API for katalyst-taxonomy
+Author: eSimplicity
+License: Proprietary
+Requires-Python: >=3.12
+Requires-Dist: fastapi>=0.115
+Requires-Dist: katalyst-engine>=2.2.1
+Requires-Dist: katalyst-taxonomy>=2.2.1
+Requires-Dist: loguru>=0.7
+Requires-Dist: mcp[cli]>=1.0
+Requires-Dist: sse-starlette>=2.0
+Requires-Dist: uvicorn>=0.30

katalyst_taxonomy_mcp-2.4.0/pyproject.toml

@@ -0,0 +1,32 @@
+[project]
+name = "katalyst-taxonomy-mcp"
+version = "2.4.0"
+description = "MCP server and REST API for katalyst-taxonomy"
+license = { text = "Proprietary" }
+requires-python = ">=3.12"
+authors = [
+    { name = "eSimplicity" }
+]
+dependencies = [
+    "katalyst-taxonomy>=2.2.1",
+    "katalyst-engine>=2.2.1",
+    "mcp[cli]>=1.0",
+    "fastapi>=0.115",
+    "uvicorn>=0.30",
+    "sse-starlette>=2.0",
+    "loguru>=0.7",
+]
+
+[project.scripts]
+katalyst-mcp = "katalyst_taxonomy_mcp.__main__:main"
+katalyst-server = "katalyst_taxonomy_mcp.rest.__main__:main"
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/katalyst_taxonomy_mcp"]
+
+[tool.hatch.build.targets.wheel.sources]
+"src" = ""

katalyst_taxonomy_mcp-2.4.0/src/katalyst_taxonomy_mcp/__init__.py

@@ -0,0 +1,11 @@
+"""MCP (Model Context Protocol) server adapter for katalyst-taxonomy.
+
+This package exposes taxonomy operations as MCP tools, resources, and prompts
+so AI coding assistants can discover, query, and manipulate taxonomy data.
+"""
+
+from __future__ import annotations
+
+from katalyst_taxonomy_mcp.server import create_mcp_server
+
+__all__ = ["create_mcp_server"]

katalyst_taxonomy_mcp-2.4.0/src/katalyst_taxonomy_mcp/__main__.py

@@ -0,0 +1,29 @@
+"""Entry point for the MCP server — runs with stdio transport."""
+
+from __future__ import annotations
+
+import sys
+from pathlib import Path
+
+
+def main() -> None:
+    """Run the MCP server over stdio."""
+    # Accept an optional --path argument
+    base_path: Path | None = None
+    args = sys.argv[1:]
+    i = 0
+    while i < len(args):
+        if args[i] == "--path" and i + 1 < len(args):
+            base_path = Path(args[i + 1])
+            i += 2
+        else:
+            i += 1
+
+    from katalyst_taxonomy_mcp.server import create_mcp_server
+
+    mcp = create_mcp_server(base_path=base_path)
+    mcp.run(transport="stdio")
+
+
+if __name__ == "__main__":
+    main()

katalyst_taxonomy_mcp-2.4.0/src/katalyst_taxonomy_mcp/prompts.py

@@ -0,0 +1,96 @@
+"""MCP prompt templates for interactive taxonomy operations."""
+
+from mcp.server.fastmcp import FastMCP
+
+
+def register_prompts(mcp: FastMCP) -> None:
+    """Register prompt templates on the MCP server."""
+
+    @mcp.prompt()
+    def create_node(node_type: str, name: str) -> str:
+        """Interactive node creation wizard with type-specific guidance.
+
+        Args:
+            node_type: The type of taxonomy node to create (e.g., system, stack, layer).
+            name: The name for the new node.
+        """
+        type_guidance = {
+            "system": (
+                "A system is a top-level organizational unit in the taxonomy. "
+                "It groups related stacks and layers that form a coherent platform.\n\n"
+                "Required fields:\n"
+                "- description: What this system represents\n"
+                "- owners: Team email addresses responsible for this system\n"
+                "- environments: Which environments this system deploys to (e.g., dev, staging, prod)"
+            ),
+            "stack": (
+                "A stack is a logical grouping of layers within a system. "
+                "It represents a deployable unit or service boundary.\n\n"
+                "Required fields:\n"
+                "- parent: The system this stack belongs to\n"
+                "- description: What this stack does\n"
+                "- owners: Team email addresses\n"
+                "- environments: Deployment environments"
+            ),
+            "layer": (
+                "A layer is the lowest-level building block in the taxonomy. "
+                "It represents a specific workload type (Docker app, Terraform infra, etc.).\n\n"
+                "Required fields:\n"
+                "- parent: The stack this layer belongs to\n"
+                "- layer_type: The workload type (e.g., app-docker, infra-terraform)\n"
+                "- description: What this layer does\n"
+                "- owners: Team email addresses\n"
+                "- environments: Deployment environments"
+            ),
+        }
+
+        guidance = type_guidance.get(
+            node_type,
+            f"Creating a '{node_type}' node. Check the registry for required fields.",
+        )
+
+        return (
+            f"I need to create a new {node_type} node named '{name}' in the taxonomy.\n\n"
+            f"{guidance}\n\n"
+            f"Please use the taxonomy_create tool to create this node. "
+            f"Ask me for any missing required fields before proceeding."
+        )
+
+    @mcp.prompt()
+    def explain_taxonomy() -> str:
+        """Explain the taxonomy structure for the current repository.
+
+        Provides context about what the taxonomy contains and how it's organized.
+        """
+        return (
+            "Please explain the taxonomy structure of this repository. "
+            "Start by using the taxonomy_tree tool to show the hierarchy, "
+            "then use taxonomy_status to show installed components. "
+            "Summarize:\n"
+            "1. How many systems, stacks, and layers exist\n"
+            "2. What environments are configured\n"
+            "3. The overall architecture the taxonomy describes\n"
+            "4. Any notable patterns (shared libraries, extensions, etc.)"
+        )
+
+    @mcp.prompt()
+    def suggest_layer_type(workload_description: str) -> str:
+        """Recommend a layer type based on a workload description.
+
+        Args:
+            workload_description: A description of the workload or service to model.
+        """
+        return (
+            f"Based on this workload description: '{workload_description}'\n\n"
+            "Please recommend an appropriate layer type. First, use the taxonomy_status "
+            "tool to see what layer types are already installed. Then suggest the best "
+            "match, explaining:\n"
+            "1. Which layer type fits best and why\n"
+            "2. What directory structure it will create\n"
+            "3. What actions (build, deploy, test) are available for it\n"
+            "4. If no existing type fits, suggest creating a custom one"
+        )
+
+    _ = create_node
+    _ = explain_taxonomy
+    _ = suggest_layer_type

katalyst_taxonomy_mcp-2.4.0/src/katalyst_taxonomy_mcp/resources.py

@@ -0,0 +1,176 @@
+"""Read-only MCP resources for taxonomy data."""
+
+from __future__ import annotations
+
+import json
+
+from mcp.server.fastmcp import FastMCP
+
+from katalyst_taxonomy_mcp.server import AppContext
+
+# Module-level reference set during lifespan startup.
+# Resources can't receive Context params for non-template URIs in FastMCP,
+# so we use this holder as a workaround.
+_app_ctx_holder: list[AppContext] = []
+
+
+def set_app_ctx(ctx: AppContext) -> None:
+    """Store the app context for resource access."""
+    _app_ctx_holder.clear()
+    _app_ctx_holder.append(ctx)
+
+
+def _get_app_ctx() -> AppContext | None:
+    """Get the stored app context, if any."""
+    return _app_ctx_holder[0] if _app_ctx_holder else None
+
+
+def register_resources(mcp: FastMCP) -> None:
+    """Register read-only resources on the MCP server."""
+
+    @mcp.resource("taxonomy://node/{name}")
+    def taxonomy_node_resource(name: str) -> str:
+        """Single taxonomy node document as JSON."""
+        app = _get_app_ctx()
+        if app is None:
+            return json.dumps({"error": "Server not initialized."})
+
+        from katalyst_taxonomy.services.serialization import serialize_document
+
+        service = app.load_taxonomy()
+        doc = service.get_document_by_name(name)
+        if doc is None:
+            return json.dumps({"error": f"Node '{name}' not found."})
+
+        payload = serialize_document(doc, service, app.base_path)
+        return json.dumps(payload, indent=2)
+
+    @mcp.resource("taxonomy://tree")
+    def taxonomy_tree_resource() -> str:
+        """Full taxonomy tree in text format."""
+        app = _get_app_ctx()
+        if app is None:
+            return "Server not initialized."
+
+        from katalyst_taxonomy.services.serialization import build_tree_lines
+
+        service = app.load_taxonomy()
+        if not service.documents:
+            return "No taxonomy documents found."
+
+        return "\n".join(build_tree_lines(service))
+
+    @mcp.resource("taxonomy://environments")
+    def taxonomy_environments_resource() -> str:
+        """Environment configurations as JSON."""
+        app = _get_app_ctx()
+        if app is None:
+            return json.dumps([])
+
+        from katalyst_taxonomy.services.serialization import serialize_document
+        from katalyst_taxonomy.services.taxonomy import TaxonomyService
+
+        repo = app.backend
+        documents = repo.load_documents()
+        env_documents = [d for d in documents if d.kind == "environment"]
+        service = TaxonomyService(documents=tuple(documents))
+
+        data = [serialize_document(env, service) for env in env_documents]
+        return json.dumps(data, indent=2)
+
+    @mcp.resource("taxonomy://registry")
+    def taxonomy_registry_resource() -> str:
+        """Node type registry metadata as JSON."""
+        from katalyst_taxonomy.engine.bridge import get_default_registry
+
+        registry = get_default_registry()
+        data: list[dict[str, object]] = []
+        for kind in registry.all_kinds():
+            desc = registry.get_node_definition(kind)
+            if desc is None:
+                continue
+            data.append(
+                {
+                    "kind": desc.describes_kind,
+                    "wing": desc.wing,
+                    "displayOrder": desc.display_order,
+                    "directoryName": desc.directory_name,
+                    "parentTypes": list(desc.allowed_parent_kinds)
+                    if desc.allowed_parent_kinds
+                    else None,
+                    "isLeaf": desc.is_leaf,
+                    "isRoot": desc.is_root,
+                    "isExtension": desc.is_extension,
+                }
+            )
+
+        return json.dumps(data, indent=2)
+
+    @mcp.resource("taxonomy://status")
+    def taxonomy_status_resource() -> str:
+        """Installed components and versions."""
+        app = _get_app_ctx()
+        if app is None:
+            return "Server not initialized."
+
+        from katalyst_taxonomy.adapters.filesystem.lock import LockFileRepository
+        from katalyst_taxonomy.services.status import StatusCode, get_status
+
+        result = get_status(app.base_path, lock_repo=LockFileRepository(base_path=app.base_path))
+
+        if result.status == StatusCode.NOT_INITIALIZED:
+            return f"No Katalyst lock file found.\nExpected: {result.lock_file_path}"
+
+        if result.status == StatusCode.ERROR:
+            return f"Error reading lock file: {result.error}"
+
+        lock = result.lock
+        assert lock is not None
+        return (
+            f"Katalyst Taxonomy Status\n"
+            f"  Version: {lock.installed.core.version}\n"
+            f"  Schema: {lock.installed.core.schema_version}\n"
+            f"  Source: {lock.installed.core.source}"
+        )
+
+    @mcp.resource("taxonomy://agents")
+    def taxonomy_agents_resource() -> str:
+        """Agent definitions list as JSON."""
+        app = _get_app_ctx()
+        if app is None:
+            return json.dumps({"agents": [], "skills": [], "error": "Server not initialized."})
+
+        from katalyst_taxonomy.agents.discovery import (
+            discover_agents_directory,
+            scan_agents_directory,
+        )
+
+        agents_dir = discover_agents_directory(app.base_path)
+        if not agents_dir:
+            return json.dumps({"agents": [], "skills": [], "error": "No .agents/ directory found."})
+
+        directory = scan_agents_directory(agents_dir)
+        data = {
+            "path": str(directory.path),
+            "agents": [
+                {
+                    "name": a.name,
+                    "description": a.description,
+                    "mode": a.mode,
+                    "source": a.source,
+                }
+                for a in directory.agents
+            ],
+            "skills": [
+                {"name": s.name, "description": s.description, "source": s.source}
+                for s in directory.skills
+            ],
+        }
+        return json.dumps(data, indent=2)
+
+    _ = taxonomy_node_resource
+    _ = taxonomy_tree_resource
+    _ = taxonomy_environments_resource
+    _ = taxonomy_registry_resource
+    _ = taxonomy_status_resource
+    _ = taxonomy_agents_resource

katalyst_taxonomy_mcp-2.4.0/src/katalyst_taxonomy_mcp/response.py

@@ -0,0 +1,55 @@
+"""Structured response helpers for MCP tools and REST API.
+
+All MCP tools and REST endpoints use these helpers to ensure consistent
+response shapes: {ok: true, data: ...} or {ok: false, error: {code, message, details}}.
+"""
+
+from __future__ import annotations
+
+from enum import StrEnum
+from typing import Any
+
+
+class ErrorCode(StrEnum):
+    """Standardized error codes for structured responses."""
+
+    NOT_FOUND = "NOT_FOUND"
+    VALIDATION_ERROR = "VALIDATION_ERROR"
+    DUPLICATE = "DUPLICATE"
+    IO_ERROR = "IO_ERROR"
+    INVALID_INPUT = "INVALID_INPUT"
+    INTERNAL_ERROR = "INTERNAL_ERROR"
+    ALREADY_EXISTS = "ALREADY_EXISTS"
+    NOT_INITIALIZED = "NOT_INITIALIZED"
+    PERMISSION_DENIED = "PERMISSION_DENIED"
+
+
+def ok(data: Any) -> dict[str, Any]:
+    """Return a successful structured response.
+
+    Args:
+        data: The response payload. Can be any JSON-serializable value.
+
+    Returns:
+        {"ok": True, "data": data}
+    """
+    return {"ok": True, "data": data}
+
+
+def err(
+    code: str | ErrorCode, message: str, details: dict[str, Any] | None = None
+) -> dict[str, Any]:
+    """Return a structured error response.
+
+    Args:
+        code: Error code from ErrorCode enum or a string.
+        message: Human-readable error message.
+        details: Optional additional context about the error.
+
+    Returns:
+        {"ok": False, "error": {"code": ..., "message": ..., "details": ...}}
+    """
+    error: dict[str, Any] = {"code": str(code), "message": message}
+    if details:
+        error["details"] = details
+    return {"ok": False, "error": error}

katalyst_taxonomy_mcp-2.4.0/src/katalyst_taxonomy_mcp/rest/__init__.py

@@ -0,0 +1,5 @@
+"""Katalyst Server - FastAPI HTTP server for taxonomy operations."""
+
+from katalyst_taxonomy_mcp.rest.app import create_app
+
+__all__ = ["create_app"]

katalyst_taxonomy_mcp-2.4.0/src/katalyst_taxonomy_mcp/rest/__main__.py

@@ -0,0 +1,103 @@
+"""Entry point for running the server."""
+
+from __future__ import annotations
+
+import argparse
+import os
+from pathlib import Path
+
+import uvicorn
+from loguru import logger
+
+from katalyst_taxonomy_mcp.rest.app import create_app
+from katalyst_taxonomy_mcp.rest.state import ServerState, save_server_state
+
+DEFAULT_IDLE_TIMEOUT = 300  # 5 minutes
+
+
+def main() -> None:
+    """Run the Katalyst server."""
+    parser = argparse.ArgumentParser(description="Katalyst Taxonomy Server")
+    parser.add_argument(
+        "--path",
+        type=Path,
+        default=Path.cwd(),
+        help="Path to taxonomy directory (default: current directory)",
+    )
+    parser.add_argument(
+        "--host",
+        type=str,
+        default="127.0.0.1",
+        help="Host to bind to (default: 127.0.0.1)",
+    )
+    parser.add_argument(
+        "--port",
+        type=int,
+        default=8000,
+        help="Port to bind to (default: 8000)",
+    )
+    parser.add_argument(
+        "--reload",
+        action="store_true",
+        help="Enable auto-reload for development",
+    )
+    parser.add_argument(
+        "--idle-timeout",
+        type=int,
+        default=DEFAULT_IDLE_TIMEOUT,
+        help=f"Idle timeout in seconds before auto-shutdown (default: {DEFAULT_IDLE_TIMEOUT}, 0 to disable)",
+    )
+    parser.add_argument(
+        "--background",
+        action="store_true",
+        help="Run in background mode (used by server manager)",
+    )
+
+    args = parser.parse_args()
+
+    resolved_path = args.path.resolve()
+
+    # Save server state for the manager to track
+    state = ServerState.create(
+        pid=os.getpid(),
+        port=args.port,
+        host=args.host,
+        path=resolved_path,
+    )
+    save_server_state(state)
+
+    if args.background:
+        # Suppress uvicorn logging in background mode
+        log_config = {
+            "version": 1,
+            "disable_existing_loggers": True,
+            "handlers": {},
+            "loggers": {"uvicorn": {"level": "WARNING"}, "uvicorn.error": {"level": "WARNING"}},
+        }
+    else:
+        log_config = None
+        logger.info(f"Starting Katalyst server on {args.host}:{args.port}")
+        logger.info(f"Taxonomy path: {resolved_path}")
+        if args.idle_timeout > 0:
+            logger.info(f"Idle timeout: {args.idle_timeout}s")
+        else:
+            logger.info("Idle timeout: disabled")
+
+    app = create_app(base_path=resolved_path, idle_timeout=args.idle_timeout)
+
+    uvicorn_kwargs: dict[str, object] = {
+        "host": args.host,
+        "port": args.port,
+    }
+
+    if log_config is not None:
+        uvicorn_kwargs["log_config"] = log_config
+
+    if args.reload:
+        uvicorn_kwargs["reload"] = True
+
+    uvicorn.run(app, **uvicorn_kwargs)  # type: ignore[arg-type]
+
+
+if __name__ == "__main__":
+    main()