ifcraftcorpus 1.1.0__py3-none-any.whl → 1.2.1__py3-none-any.whl

ifcraftcorpus/mcp_server.py

@@ -10,6 +10,7 @@ Features:
     - Retrieve specific documents
     - List available documents and clusters
     - Get corpus statistics
+    - Subagent prompts for IF authoring workflows
 
 Installation:
     The MCP server requires the ``mcp`` extra::
@@ -51,18 +52,94 @@ Tools:
     corpus_stats: Get corpus statistics.
     embeddings_status: Check embedding provider and index status.
     build_embeddings: Build or rebuild semantic search embeddings.
+
+Prompts:
+    if_story_architect: System prompt for an IF Story Architect agent.
+    if_prose_writer: System prompt for an IF Prose Writer agent.
+    if_quality_reviewer: System prompt for an IF Quality Reviewer agent.
+    if_genre_consultant: System prompt for an IF Genre Consultant agent.
+    if_world_curator: System prompt for an IF World Curator agent.
+    if_platform_advisor: System prompt for an IF Platform Advisor agent.
 """
 
 from __future__ import annotations
 
+import logging
 import os
+import sys
+from collections.abc import Callable
 from pathlib import Path
-from typing import Literal
+from typing import TYPE_CHECKING, Any, Literal, TypeVar
 
 from fastmcp import FastMCP
+from fastmcp.prompts import Message
+from mcp.types import PromptMessage
 
+from ifcraftcorpus.logging_utils import configure_logging
 from ifcraftcorpus.search import Corpus
 
+_CONFIGURED_LOG_LEVEL = configure_logging()
+logger = logging.getLogger(__name__)
+if _CONFIGURED_LOG_LEVEL is not None:
+    logger.info("MCP logging enabled at %s", logging.getLevelName(_CONFIGURED_LOG_LEVEL))
+
+
+def _truncate(value: str, limit: int = 200) -> str:
+    """Truncate long strings for safe structured logging."""
+
+    if len(value) <= limit:
+        return value
+    return f"{value[:limit]}..."
+
+
+def _get_subagents_dir() -> Path:
+    """Get the path to the subagents directory.
+
+    Returns the subagents directory from either:
+    1. The installed package location (share/ifcraftcorpus/subagents)
+    2. The development location (project root/subagents)
+    """
+    # Try installed location first
+    if sys.prefix != sys.base_prefix:
+        # We're in a virtual environment
+        installed_path = Path(sys.prefix) / "share" / "ifcraftcorpus" / "subagents"
+        if installed_path.exists():
+            logger.debug("Using installed subagents directory: %s", installed_path)
+            return installed_path
+
+    # Try development location (relative to this file)
+    dev_path = Path(__file__).parent.parent.parent.parent / "subagents"
+    if dev_path.exists():
+        logger.debug("Using development subagents directory: %s", dev_path)
+        return dev_path
+
+    # Fallback to current directory
+    fallback = Path("subagents")
+    logger.debug("Using fallback subagents directory: %s", fallback)
+    return fallback
+
+
+def _load_subagent_template(name: str) -> str:
+    """Load a subagent template by name.
+
+    Args:
+        name: Template name (without .md extension)
+
+    Returns:
+        The template content as a string.
+
+    Raises:
+        FileNotFoundError: If the template doesn't exist.
+    """
+    subagents_dir = _get_subagents_dir()
+    template_path = subagents_dir / f"{name}.md"
+    if not template_path.exists():
+        logger.error("Subagent template missing: %s", template_path)
+        raise FileNotFoundError(f"Subagent template not found: {template_path}")
+    logger.debug("Loaded subagent template %s", template_path.name)
+    return template_path.read_text(encoding="utf-8")
+
+
 # Initialize FastMCP server
 mcp = FastMCP(
     name="IF Craft Corpus",
@@ -74,6 +151,16 @@ mcp = FastMCP(
     """,
 )
 
+if TYPE_CHECKING:
+    TCallable = TypeVar("TCallable", bound=Callable[..., Any])
+
+    def tool(func: TCallable, /) -> TCallable: ...
+
+    def prompt(*args: Any, **kwargs: Any) -> Callable[[TCallable], TCallable]: ...
+else:  # pragma: no cover - runtime aliases for decorators
+    tool = mcp.tool
+    prompt = mcp.prompt
+
 # Global corpus instance (initialized on first use)
 _corpus: Corpus | None = None
 
@@ -89,16 +176,17 @@ def get_corpus() -> Corpus:
     """
     global _corpus
     if _corpus is None:
+        logger.info("Initializing shared Corpus instance for MCP server")
         _corpus = Corpus()
     return _corpus
 
 
-@mcp.tool
+@tool
 def search_corpus(
     query: str,
     cluster: str | None = None,
     limit: int = 5,
-) -> list[dict]:
+) -> list[dict[str, Any]]:
     """Search the IF Craft Corpus for writing guidance.
 
     Use this tool to find craft advice for interactive fiction writing,
@@ -120,8 +208,21 @@ def search_corpus(
     """
     limit = max(1, min(20, limit))
 
+    logger.debug(
+        "search_corpus(query=%r, cluster=%s, limit=%s)",
+        _truncate(query),
+        cluster,
+        limit,
+    )
+
     corpus = get_corpus()
-    results = corpus.search(query, cluster=cluster, limit=limit)
+    try:
+        results = corpus.search(query, cluster=cluster, limit=limit)
+    except Exception:  # pragma: no cover - defensive logging
+        logger.exception("search_corpus failed")
+        raise
+
+    logger.debug("search_corpus returning %s results", len(results))
 
     return [
         {
@@ -135,8 +236,8 @@ def search_corpus(
     ]
 
 
-@mcp.tool
-def get_document(name: str) -> dict | None:
+@tool
+def get_document(name: str) -> dict[str, Any] | None:
     """Get a specific document from the IF Craft Corpus.
 
     Use this tool when you need the full content of a known document,
@@ -149,12 +250,18 @@ def get_document(name: str) -> dict | None:
     Returns:
         Full document with title, summary, cluster, topics, and all sections.
     """
+    logger.debug("get_document(%s)", name)
     corpus = get_corpus()
-    return corpus.get_document(name)
+    document = corpus.get_document(name)
+    if document is None:
+        logger.info("Document not found: %s", name)
+    else:
+        logger.debug("Document %s retrieved", name)
+    return document
 
 
-@mcp.tool
-def list_documents(cluster: str | None = None) -> list[dict]:
+@tool
+def list_documents(cluster: str | None = None) -> list[dict[str, Any]]:
     """List all documents in the IF Craft Corpus.
 
     Use this tool to discover what craft guidance is available.
@@ -165,17 +272,19 @@ def list_documents(cluster: str | None = None) -> list[dict]:
     Returns:
         List of documents with name, title, cluster, and topics.
     """
+    logger.debug("list_documents(cluster=%s)", cluster)
     corpus = get_corpus()
     docs = corpus.list_documents()
 
     if cluster:
         docs = [d for d in docs if d["cluster"] == cluster]
 
+    logger.debug("list_documents returning %s entries", len(docs))
     return docs
 
 
-@mcp.tool
-def list_clusters() -> list[dict]:
+@tool
+def list_clusters() -> list[dict[str, Any]]:
     """List all topic clusters in the IF Craft Corpus.
 
     Each cluster groups related craft documents. Use this to understand
@@ -184,37 +293,48 @@ def list_clusters() -> list[dict]:
     Returns:
         List of clusters with names and document counts.
     """
+    logger.debug("list_clusters invoked")
     corpus = get_corpus()
     clusters = corpus.list_clusters()
     docs = corpus.list_documents()
 
     # Count documents per cluster
-    counts = {}
+    counts: dict[str, int] = {}
     for d in docs:
         c = d["cluster"]
         counts[c] = counts.get(c, 0) + 1
 
-    return [{"name": c, "document_count": counts.get(c, 0)} for c in clusters]
+    cluster_info = [{"name": c, "document_count": counts.get(c, 0)} for c in clusters]
+    logger.debug("list_clusters returning %s clusters", len(cluster_info))
+    return cluster_info
 
 
-@mcp.tool
-def corpus_stats() -> dict:
+@tool
+def corpus_stats() -> dict[str, Any]:
     """Get statistics about the IF Craft Corpus.
 
     Returns:
         Statistics including document count, cluster count, and availability.
     """
+    logger.debug("corpus_stats invoked")
     corpus = get_corpus()
-    return {
+    stats = {
         "document_count": corpus.document_count(),
         "cluster_count": len(corpus.list_clusters()),
         "clusters": corpus.list_clusters(),
         "semantic_search_available": corpus.has_semantic_search,
     }
+    logger.debug(
+        "corpus_stats: docs=%s clusters=%s semantic=%s",
+        stats["document_count"],
+        stats["cluster_count"],
+        stats["semantic_search_available"],
+    )
+    return stats
 
 
-@mcp.tool
-def embeddings_status() -> dict:
+@tool
+def embeddings_status() -> dict[str, Any]:
     """Get status of embedding providers and index.
 
     Returns information about available embedding providers (Ollama, OpenAI,
@@ -223,7 +343,8 @@ def embeddings_status() -> dict:
     Returns:
         Dict with provider availability and embedding index status.
     """
-    result = {
+    logger.debug("embeddings_status invoked")
+    result: dict[str, Any] = {
         "semantic_search_available": get_corpus().has_semantic_search,
         "providers": {},
         "saved_embeddings": None,
@@ -251,13 +372,15 @@ def embeddings_status() -> dict:
                     "model": provider.model if available else None,
                     "dimension": provider.dimension if available else None,
                 }
-            except Exception:
+            except Exception as exc:  # pragma: no cover - defensive logging
+                logger.warning("Failed to inspect embedding provider %s: %s", name, exc)
                 result["providers"][name] = {"available": False, "error": "import_failed"}
 
         # Auto-detect best provider
         auto = get_embedding_provider()
         result["auto_detected_provider"] = auto.provider_name if auto else None
     except ImportError:
+        logger.warning("Embedding providers module not importable for status call")
         result["providers_error"] = "providers module not available"
 
     # Check for saved embeddings
@@ -274,14 +397,20 @@ def embeddings_status() -> dict:
             "count": len(meta.get("metadata", [])),
         }
 
+    logger.debug(
+        "embeddings_status semantic=%s providers=%s saved=%s",
+        result["semantic_search_available"],
+        list(result["providers"].keys()),
+        bool(result["saved_embeddings"]),
+    )
     return result
 
 
-@mcp.tool
+@tool
 def build_embeddings(
     provider: str | None = None,
     force: bool = False,
-) -> dict:
+) -> dict[str, Any]:
     """Build or rebuild the embedding index for semantic search.
 
     Builds embeddings for all corpus documents using the specified provider.
@@ -303,6 +432,8 @@ def build_embeddings(
     """
     global _corpus
 
+    logger.info("build_embeddings requested provider=%s force=%s", provider, force)
+
     try:
         from ifcraftcorpus.providers import (
             OllamaEmbeddings,
@@ -311,6 +442,7 @@ def build_embeddings(
             get_embedding_provider,
         )
     except ImportError:
+        logger.warning("Embedding provider modules not installed")
         return {
             "error": "Embedding providers not available. "
             "Install with [embeddings-api] or [embeddings] extras."
@@ -325,6 +457,7 @@ def build_embeddings(
             "sentence_transformers": SentenceTransformersEmbeddings,
         }
         if provider not in provider_map:
+            logger.warning("Unknown embeddings provider requested: %s", provider)
             return {
                 "error": f"Unknown provider: {provider}. Use: ollama, openai, sentence_transformers"
             }
@@ -333,12 +466,14 @@ def build_embeddings(
         embedding_provider = get_embedding_provider()
 
     if not embedding_provider:
+        logger.warning("No embedding provider available for build request")
         return {
             "error": "No embedding provider available. "
             "Configure Ollama, set OPENAI_API_KEY, or install sentence-transformers."
         }
 
     if not embedding_provider.check_availability():
+        logger.warning("Embedding provider %s unavailable", embedding_provider.provider_name)
         return {"error": f"Provider {embedding_provider.provider_name} is not available."}
 
     # Configure paths
@@ -346,6 +481,7 @@ def build_embeddings(
 
     # Check if already exists
     if not force and embeddings_path.exists() and (embeddings_path / "metadata.json").exists():
+        logger.info("Embedding build skipped; existing index at %s", embeddings_path)
         return {
             "status": "skipped",
             "message": "Embeddings already exist. Use force=True to rebuild.",
@@ -360,6 +496,12 @@ def build_embeddings(
 
     # Build embeddings
     count = corpus.build_embeddings(force=force)
+    logger.info(
+        "Embedding build complete items=%s provider=%s model=%s",
+        count,
+        embedding_provider.provider_name,
+        embedding_provider.model,
+    )
 
     # Update global corpus to use new embeddings
     _corpus = Corpus(embeddings_path=embeddings_path)
@@ -373,6 +515,258 @@ def build_embeddings(
     }
 
 
+# =============================================================================
+# Subagent Prompts
+# =============================================================================
+#
+# These prompts provide system prompts for specialized IF authoring agents.
+# Each agent has a specific role in the IF creation workflow.
+
+
+@prompt(
+    name="if_story_architect",
+    description="System prompt for an IF Story Architect - an orchestrator agent that "
+    "plans narrative structure, decomposes IF projects, and coordinates creation.",
+)
+def if_story_architect_prompt(
+    project_name: str | None = None,
+    genre: str | None = None,
+) -> list[PromptMessage]:
+    """Get the IF Story Architect system prompt.
+
+    Args:
+        project_name: Optional project name to include in the prompt context.
+        genre: Optional genre to emphasize (fantasy, horror, mystery, etc.).
+
+    Returns:
+        System prompt messages for the Story Architect agent.
+    """
+    template = _load_subagent_template("if_story_architect")
+
+    # Add optional context
+    context_parts = []
+    if project_name:
+        context_parts.append(f"Project: {project_name}")
+    if genre:
+        context_parts.append(f"Genre: {genre}")
+
+    if context_parts:
+        context = "\n\n---\n\n## Current Project Context\n\n" + "\n".join(context_parts)
+        template = template + context
+
+    return [Message(template, role="user")]
+
+
+@prompt(
+    name="if_prose_writer",
+    description="System prompt for an IF Prose Writer - a specialist agent that "
+    "creates narrative content including prose, dialogue, and scene text.",
+)
+def if_prose_writer_prompt(
+    genre: str | None = None,
+    pov: str | None = None,
+) -> list[PromptMessage]:
+    """Get the IF Prose Writer system prompt.
+
+    Args:
+        genre: Optional genre to emphasize (fantasy, horror, mystery, etc.).
+        pov: Optional point of view (first, second, third).
+
+    Returns:
+        System prompt messages for the Prose Writer agent.
+    """
+    template = _load_subagent_template("if_prose_writer")
+
+    # Add optional context
+    context_parts = []
+    if genre:
+        context_parts.append(f"Genre: {genre}")
+    if pov:
+        context_parts.append(f"Point of View: {pov}")
+
+    if context_parts:
+        context = "\n\n---\n\n## Current Project Context\n\n" + "\n".join(context_parts)
+        template = template + context
+
+    return [Message(template, role="user")]
+
+
+@prompt(
+    name="if_quality_reviewer",
+    description="System prompt for an IF Quality Reviewer - a validator agent that "
+    "reviews IF content for craft quality, consistency, and standards compliance.",
+)
+def if_quality_reviewer_prompt(
+    focus_areas: str | None = None,
+) -> list[PromptMessage]:
+    """Get the IF Quality Reviewer system prompt.
+
+    Args:
+        focus_areas: Optional comma-separated list of areas to focus on
+                    (e.g., "voice,pacing,continuity").
+
+    Returns:
+        System prompt messages for the Quality Reviewer agent.
+    """
+    template = _load_subagent_template("if_quality_reviewer")
+
+    if focus_areas:
+        context = f"\n\n---\n\n## Review Focus\n\nPrioritize these areas: {focus_areas}"
+        template = template + context
+
+    return [Message(template, role="user")]
+
+
+@prompt(
+    name="if_genre_consultant",
+    description="System prompt for an IF Genre Consultant - a researcher agent that "
+    "provides genre-specific guidance on conventions, tropes, and reader expectations.",
+)
+def if_genre_consultant_prompt(
+    primary_genre: str | None = None,
+    secondary_genre: str | None = None,
+) -> list[PromptMessage]:
+    """Get the IF Genre Consultant system prompt.
+
+    Args:
+        primary_genre: Optional primary genre to focus on.
+        secondary_genre: Optional secondary genre for blending advice.
+
+    Returns:
+        System prompt messages for the Genre Consultant agent.
+    """
+    template = _load_subagent_template("if_genre_consultant")
+
+    context_parts = []
+    if primary_genre:
+        context_parts.append(f"Primary Genre: {primary_genre}")
+    if secondary_genre:
+        context_parts.append(f"Secondary Genre: {secondary_genre}")
+
+    if context_parts:
+        context = "\n\n---\n\n## Genre Focus\n\n" + "\n".join(context_parts)
+        template = template + context
+
+    return [Message(template, role="user")]
+
+
+@prompt(
+    name="if_world_curator",
+    description="System prompt for an IF World Curator - a curator agent that "
+    "maintains world consistency, manages canon, and ensures setting coherence.",
+)
+def if_world_curator_prompt(
+    world_name: str | None = None,
+    setting_type: str | None = None,
+) -> list[PromptMessage]:
+    """Get the IF World Curator system prompt.
+
+    Args:
+        world_name: Optional name of the world/setting.
+        setting_type: Optional setting type (e.g., "fantasy medieval", "sci-fi space").
+
+    Returns:
+        System prompt messages for the World Curator agent.
+    """
+    template = _load_subagent_template("if_world_curator")
+
+    context_parts = []
+    if world_name:
+        context_parts.append(f"World: {world_name}")
+    if setting_type:
+        context_parts.append(f"Setting Type: {setting_type}")
+
+    if context_parts:
+        context = "\n\n---\n\n## World Context\n\n" + "\n".join(context_parts)
+        template = template + context
+
+    return [Message(template, role="user")]
+
+
+@prompt(
+    name="if_platform_advisor",
+    description="System prompt for an IF Platform Advisor - a researcher agent that "
+    "provides guidance on tools, platforms, and technical implementation.",
+)
+def if_platform_advisor_prompt(
+    target_platform: str | None = None,
+    team_size: str | None = None,
+) -> list[PromptMessage]:
+    """Get the IF Platform Advisor system prompt.
+
+    Args:
+        target_platform: Optional target platform if already decided.
+        team_size: Optional team size (solo, small, large).
+
+    Returns:
+        System prompt messages for the Platform Advisor agent.
+    """
+    template = _load_subagent_template("if_platform_advisor")
+
+    context_parts = []
+    if target_platform:
+        context_parts.append(f"Target Platform: {target_platform}")
+    if team_size:
+        context_parts.append(f"Team Size: {team_size}")
+
+    if context_parts:
+        context = "\n\n---\n\n## Project Context\n\n" + "\n".join(context_parts)
+        template = template + context
+
+    return [Message(template, role="user")]
+
+
+@tool
+def list_subagents() -> list[dict[str, Any]]:
+    """List all available IF subagent prompts.
+
+    Returns a list of subagent templates that can be used as system prompts
+    for specialized IF authoring agents.
+
+    Returns:
+        List of subagents with name, description, and parameters.
+    """
+    logger.debug("list_subagents invoked")
+    return [
+        {
+            "name": "if_story_architect",
+            "description": "Orchestrator that plans narrative structure and coordinates creation",
+            "archetype": "orchestrator",
+            "parameters": ["project_name", "genre"],
+        },
+        {
+            "name": "if_prose_writer",
+            "description": "Specialist that creates narrative prose, dialogue, and scene text",
+            "archetype": "creator",
+            "parameters": ["genre", "pov"],
+        },
+        {
+            "name": "if_quality_reviewer",
+            "description": "Validator agent that reviews content for quality and consistency",
+            "archetype": "validator",
+            "parameters": ["focus_areas"],
+        },
+        {
+            "name": "if_genre_consultant",
+            "description": "Researcher agent for genre conventions, tropes, and expectations",
+            "archetype": "researcher",
+            "parameters": ["primary_genre", "secondary_genre"],
+        },
+        {
+            "name": "if_world_curator",
+            "description": "Curator agent that maintains world consistency and canon",
+            "archetype": "curator",
+            "parameters": ["world_name", "setting_type"],
+        },
+        {
+            "name": "if_platform_advisor",
+            "description": "Researcher agent for tools, platforms, and technical implementation",
+            "archetype": "researcher",
+            "parameters": ["target_platform", "team_size"],
+        },
+    ]
+
+
 def run_server(
     transport: Literal["stdio", "http"] = "stdio",
     host: str = "127.0.0.1",
@@ -400,8 +794,10 @@ def run_server(
         >>> run_server(transport="http", host="0.0.0.0", port=8080)
     """
     if transport == "http":
+        logger.info("Starting MCP server (http) host=%s port=%s", host, port)
         mcp.run(transport="http", host=host, port=port)
     else:
+        logger.info("Starting MCP server (stdio)")
         mcp.run()
 
 

ifcraftcorpus/providers.py

@@ -21,7 +21,7 @@ from dataclasses import dataclass
 from typing import TYPE_CHECKING
 
 if TYPE_CHECKING:
-    pass
+    from sentence_transformers import SentenceTransformer
 
 logger = logging.getLogger(__name__)
 
@@ -283,7 +283,7 @@ class OpenAIEmbeddings(EmbeddingProvider):
                     "https://api.openai.com/v1/models",
                     headers={"Authorization": f"Bearer {self._api_key}"},
                 )
-                return response.status_code == 200
+                return bool(response.status_code == 200)
 
         except httpx.RequestError as e:
             logger.debug(f"OpenAI availability check failed: {e}")
@@ -314,12 +314,12 @@ class SentenceTransformersEmbeddings(EmbeddingProvider):
         """
         self._model_name = model or DEFAULT_MODELS["sentence-transformers"]
         self._dimension = MODEL_DIMENSIONS.get(self._model_name, 384)
-        self._model_instance = None
+        self._model_instance: SentenceTransformer | None = None
 
         if not lazy_load:
             self._load_model()
 
-    def _load_model(self):
+    def _load_model(self) -> SentenceTransformer:
         """Load the sentence transformer model."""
         if self._model_instance is None:
             try: