cfabric-mcp 0.1.0__tar.gz

cfabric_mcp-0.1.0/PKG-INFO

@@ -0,0 +1,164 @@
+Metadata-Version: 2.4
+Name: cfabric-mcp
+Version: 0.1.0
+Summary: MCP server for Context Fabric corpus operations
+Author: Cody Kingham
+License: MIT
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3.13
+Requires-Python: >=3.13
+Description-Content-Type: text/markdown
+Requires-Dist: context-fabric>=0.2.0
+Requires-Dist: mcp<2,>=1.0
+Requires-Dist: uvicorn>=0.32.0
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0; extra == "dev"
+Requires-Dist: pytest-asyncio; extra == "dev"
+
+# Context-Fabric MCP Server
+
+Query Context-Fabric corpora via MCP (Model Context Protocol).
+
+## Installation
+
+```bash
+pip install cfabric-mcp
+```
+
+## Transports
+
+The server supports three transport modes:
+
+| Transport | Flag | Use Case |
+|-----------|------|----------|
+| stdio | (default) | Claude Desktop, local MCP clients |
+| SSE | `--sse PORT` | Cursor, remote MCP clients |
+| Streamable HTTP | `--http PORT` | Production deployments |
+
+## Usage
+
+```bash
+# stdio transport (Claude Desktop)
+cfabric-mcp --corpus /path/to/bhsa
+
+# SSE transport (Cursor, remote clients)
+cfabric-mcp --corpus /path/to/bhsa --sse 8000
+
+# Streamable HTTP transport (production)
+cfabric-mcp --corpus /path/to/bhsa --http 8000
+```
+
+### Options
+
+```bash
+--corpus PATH              # Corpus to load (required, repeatable)
+--corpus name=PATH         # Named corpus
+--sse PORT                 # SSE transport on port (endpoint: /sse)
+--http PORT                # Streamable HTTP transport on port (endpoint: /mcp)
+--host HOST                # Host to bind (default: 0.0.0.0)
+--features "sp lex"        # Load only specific features
+--verbose                  # Debug logging
+```
+
+## Tools
+
+The server exposes 10 MCP tools organized in layers for efficient discovery.
+
+> **Note:** A usage guide is automatically provided to clients via the MCP `instructions` field at connection time.
+
+### Discovery Tools
+
+| Tool | Description |
+|------|-------------|
+| `list_corpora` | List loaded corpora |
+| `describe_corpus` | Get corpus structure (node types, sections) |
+| `list_features` | Browse features with optional node_type filter |
+| `describe_feature` | Get feature details with sample values |
+| `get_text_formats` | Get text encoding samples (cached) |
+
+### Search Tools
+
+| Tool | Description |
+|------|-------------|
+| `search` | Pattern search (results/count/statistics/passages) |
+| `search_continue` | Paginate search results |
+| `search_syntax_guide` | Search syntax docs (section-based) |
+
+### Data Access Tools
+
+| Tool | Description |
+|------|-------------|
+| `get_passages` | Get text by section references |
+| `get_node_features` | Get feature values for nodes |
+
+## Discovery Flow
+
+The tools are designed for hierarchical, iterative discovery:
+
+```
+describe_corpus()
+│
+├─► list_features()                  → Browse all features
+│       └─► describe_feature("sp")   → Full details + samples
+│
+├─► list_features(node_types=["word"])  → Filter by node type
+│       └─► describe_feature(...)
+│
+└─► get_text_formats()               → When encoding matters
+
+        ↓
+    search()  → Execute queries
+```
+
+**Typical workflow:**
+1. `describe_corpus()` - Get structure overview
+2. `list_features()` or `list_features(node_types=["word"])` - Browse available features
+3. `describe_feature("sp")` - Deep dive into specific feature with sample values
+4. `search_syntax_guide()` - Get search syntax help (section-based)
+5. `search()` - Execute search queries
+
+### Search Return Types
+
+| Type | Description |
+|------|-------------|
+| `results` | Paginated node info with cursor (default) |
+| `count` | Total count only |
+| `statistics` | Feature value distributions |
+| `passages` | Formatted text passages |
+
+## Client Configuration
+
+### Claude Desktop (stdio)
+
+Add to `~/Library/Application Support/Claude/claude_desktop_config.json`:
+
+```json
+{
+  "mcpServers": {
+    "context-fabric": {
+      "command": "/path/to/venv/bin/cfabric-mcp",
+      "args": ["--corpus", "/path/to/bhsa"]
+    }
+  }
+}
+```
+
+### Cursor (SSE)
+
+Start server:
+```bash
+cfabric-mcp --corpus /path/to/bhsa --sse 8000
+```
+
+Configure Cursor to connect to: `http://localhost:8000/sse`
+
+### Custom MCP Clients
+
+For SSE transport, connect to `http://host:port/sse`
+For Streamable HTTP, connect to `http://host:port/mcp`
+
+## License
+
+MIT

cfabric_mcp-0.1.0/README.md

@@ -0,0 +1,145 @@
+# Context-Fabric MCP Server
+
+Query Context-Fabric corpora via MCP (Model Context Protocol).
+
+## Installation
+
+```bash
+pip install cfabric-mcp
+```
+
+## Transports
+
+The server supports three transport modes:
+
+| Transport | Flag | Use Case |
+|-----------|------|----------|
+| stdio | (default) | Claude Desktop, local MCP clients |
+| SSE | `--sse PORT` | Cursor, remote MCP clients |
+| Streamable HTTP | `--http PORT` | Production deployments |
+
+## Usage
+
+```bash
+# stdio transport (Claude Desktop)
+cfabric-mcp --corpus /path/to/bhsa
+
+# SSE transport (Cursor, remote clients)
+cfabric-mcp --corpus /path/to/bhsa --sse 8000
+
+# Streamable HTTP transport (production)
+cfabric-mcp --corpus /path/to/bhsa --http 8000
+```
+
+### Options
+
+```bash
+--corpus PATH              # Corpus to load (required, repeatable)
+--corpus name=PATH         # Named corpus
+--sse PORT                 # SSE transport on port (endpoint: /sse)
+--http PORT                # Streamable HTTP transport on port (endpoint: /mcp)
+--host HOST                # Host to bind (default: 0.0.0.0)
+--features "sp lex"        # Load only specific features
+--verbose                  # Debug logging
+```
+
+## Tools
+
+The server exposes 10 MCP tools organized in layers for efficient discovery.
+
+> **Note:** A usage guide is automatically provided to clients via the MCP `instructions` field at connection time.
+
+### Discovery Tools
+
+| Tool | Description |
+|------|-------------|
+| `list_corpora` | List loaded corpora |
+| `describe_corpus` | Get corpus structure (node types, sections) |
+| `list_features` | Browse features with optional node_type filter |
+| `describe_feature` | Get feature details with sample values |
+| `get_text_formats` | Get text encoding samples (cached) |
+
+### Search Tools
+
+| Tool | Description |
+|------|-------------|
+| `search` | Pattern search (results/count/statistics/passages) |
+| `search_continue` | Paginate search results |
+| `search_syntax_guide` | Search syntax docs (section-based) |
+
+### Data Access Tools
+
+| Tool | Description |
+|------|-------------|
+| `get_passages` | Get text by section references |
+| `get_node_features` | Get feature values for nodes |
+
+## Discovery Flow
+
+The tools are designed for hierarchical, iterative discovery:
+
+```
+describe_corpus()
+│
+├─► list_features()                  → Browse all features
+│       └─► describe_feature("sp")   → Full details + samples
+│
+├─► list_features(node_types=["word"])  → Filter by node type
+│       └─► describe_feature(...)
+│
+└─► get_text_formats()               → When encoding matters
+
+        ↓
+    search()  → Execute queries
+```
+
+**Typical workflow:**
+1. `describe_corpus()` - Get structure overview
+2. `list_features()` or `list_features(node_types=["word"])` - Browse available features
+3. `describe_feature("sp")` - Deep dive into specific feature with sample values
+4. `search_syntax_guide()` - Get search syntax help (section-based)
+5. `search()` - Execute search queries
+
+### Search Return Types
+
+| Type | Description |
+|------|-------------|
+| `results` | Paginated node info with cursor (default) |
+| `count` | Total count only |
+| `statistics` | Feature value distributions |
+| `passages` | Formatted text passages |
+
+## Client Configuration
+
+### Claude Desktop (stdio)
+
+Add to `~/Library/Application Support/Claude/claude_desktop_config.json`:
+
+```json
+{
+  "mcpServers": {
+    "context-fabric": {
+      "command": "/path/to/venv/bin/cfabric-mcp",
+      "args": ["--corpus", "/path/to/bhsa"]
+    }
+  }
+}
+```
+
+### Cursor (SSE)
+
+Start server:
+```bash
+cfabric-mcp --corpus /path/to/bhsa --sse 8000
+```
+
+Configure Cursor to connect to: `http://localhost:8000/sse`
+
+### Custom MCP Clients
+
+For SSE transport, connect to `http://host:port/sse`
+For Streamable HTTP, connect to `http://host:port/mcp`
+
+## License
+
+MIT

cfabric_mcp-0.1.0/cfabric_mcp/__init__.py

@@ -0,0 +1,38 @@
+"""Context-Fabric MCP Server.
+
+This package provides an MCP (Model Context Protocol) server that exposes
+Context-Fabric corpus operations to AI agents.
+
+Usage:
+    # Run as CLI
+    cfabric-mcp
+
+    # Or import and run programmatically
+    from cfabric_mcp import mcp
+    mcp.run(transport="stdio")
+"""
+
+import logging
+import sys
+
+# Configure logging for MCP server
+# Use stderr since stdout is reserved for MCP protocol messages
+_handler = logging.StreamHandler(sys.stderr)
+_handler.setFormatter(
+    logging.Formatter(
+        fmt="%(asctime)s [%(levelname)s] %(name)s: %(message)s",
+        datefmt="%Y-%m-%d %H:%M:%S",
+    )
+)
+
+# Create package logger
+logger = logging.getLogger("cfabric_mcp")
+logger.addHandler(_handler)
+logger.setLevel(logging.INFO)
+
+from cfabric_mcp.server import mcp, main
+from cfabric_mcp.corpus_manager import corpus_manager, CorpusManager
+
+__version__ = "0.1.0"
+
+__all__ = ["mcp", "main", "corpus_manager", "CorpusManager", "logger", "__version__"]

cfabric_mcp-0.1.0/cfabric_mcp/cache.py

@@ -0,0 +1,298 @@
+"""Search result caching for Context-Fabric MCP server.
+
+Caches search results by (corpus, template) to avoid re-running expensive queries.
+All return_types (results, count, statistics, passages) can draw from the same cache.
+"""
+
+from __future__ import annotations
+
+import logging
+import threading
+import time
+import uuid
+from dataclasses import dataclass, field
+from typing import Any, Callable
+
+logger = logging.getLogger("cfabric_mcp.cache")
+
+
+@dataclass
+class CachedSearchResult:
+    """A cached search result.
+
+    Attributes:
+        cursor_id: UUID for pagination/lookup
+        corpus: The corpus name
+        template: The search template
+        results: Raw search results (list of node ID tuples)
+        created_at: Unix timestamp when cached
+        expires_at: Unix timestamp when cache entry expires
+        last_accessed: Unix timestamp of last access (for LRU)
+    """
+
+    cursor_id: str
+    corpus: str
+    template: str
+    results: list[tuple[int, ...]]
+    created_at: float
+    expires_at: float
+    last_accessed: float = field(default_factory=time.time)
+
+    @property
+    def is_expired(self) -> bool:
+        """Check if this cache entry has expired."""
+        return time.time() > self.expires_at
+
+    def touch(self) -> None:
+        """Update last accessed time."""
+        self.last_accessed = time.time()
+
+
+class SearchCache:
+    """In-memory cache for search results.
+
+    Caches by (corpus, template) key. Different return_types and parameters
+    can reuse the same cached results.
+
+    Thread-safe for concurrent access.
+    """
+
+    def __init__(
+        self,
+        default_ttl: int = 300,  # 5 minutes
+        max_entries: int = 100,
+        max_results_per_entry: int = 10000,
+    ) -> None:
+        """Initialize the search cache.
+
+        Args:
+            default_ttl: Default time-to-live in seconds
+            max_entries: Maximum number of cached searches
+            max_results_per_entry: Maximum results to cache per search
+        """
+        self.default_ttl = default_ttl
+        self.max_entries = max_entries
+        self.max_results_per_entry = max_results_per_entry
+
+        # Cache storage: key -> CachedSearchResult
+        self._cache: dict[tuple[str, str], CachedSearchResult] = {}
+
+        # Also index by cursor_id for pagination
+        self._by_cursor: dict[str, CachedSearchResult] = {}
+
+        # Lock for thread safety
+        self._lock = threading.RLock()
+
+    def get_or_execute(
+        self,
+        corpus: str,
+        template: str,
+        search_fn: Callable[[], list[tuple[int, ...]]],
+        ttl: int | None = None,
+    ) -> CachedSearchResult:
+        """Get cached result or execute search and cache it.
+
+        Args:
+            corpus: Corpus name
+            template: Search template
+            search_fn: Function to execute search if not cached
+            ttl: Optional TTL override
+
+        Returns:
+            CachedSearchResult with the search results
+        """
+        key = (corpus, template.strip())
+        ttl = ttl or self.default_ttl
+
+        with self._lock:
+            # Check cache
+            cached = self._cache.get(key)
+            if cached and not cached.is_expired:
+                logger.debug(
+                    "Cache hit for template: %s...",
+                    template[:50].replace("\n", " ")
+                )
+                cached.touch()
+                return cached
+
+            # Cache miss or expired - execute search
+            logger.debug(
+                "Cache miss for template: %s...",
+                template[:50].replace("\n", " ")
+            )
+
+            # Run the search
+            results = search_fn()
+
+            # Sort by node-tuples for consistent ordering
+            results = sorted(results)
+
+            # Limit results to max_results_per_entry
+            if len(results) > self.max_results_per_entry:
+                logger.warning(
+                    "Truncating cache entry from %d to %d results",
+                    len(results),
+                    self.max_results_per_entry,
+                )
+                results = results[: self.max_results_per_entry]
+
+            # Create cache entry
+            now = time.time()
+            cursor_id = str(uuid.uuid4())
+            entry = CachedSearchResult(
+                cursor_id=cursor_id,
+                corpus=corpus,
+                template=template,
+                results=results,
+                created_at=now,
+                expires_at=now + ttl,
+                last_accessed=now,
+            )
+
+            # Evict old entries if needed
+            self._evict_if_needed()
+
+            # Store in cache
+            self._cache[key] = entry
+            self._by_cursor[cursor_id] = entry
+
+            return entry
+
+    def get_by_cursor(self, cursor_id: str) -> CachedSearchResult | None:
+        """Get cached result by cursor ID.
+
+        Args:
+            cursor_id: The cursor ID from a previous search
+
+        Returns:
+            CachedSearchResult if found and not expired, None otherwise
+        """
+        with self._lock:
+            entry = self._by_cursor.get(cursor_id)
+            if entry and not entry.is_expired:
+                entry.touch()
+                return entry
+            return None
+
+    def get_page(
+        self,
+        cursor_id: str,
+        offset: int,
+        limit: int,
+    ) -> tuple[list[tuple[int, ...]], bool, int] | None:
+        """Get a page of results from a cached search.
+
+        Args:
+            cursor_id: The cursor ID
+            offset: Number of results to skip
+            limit: Maximum results to return
+
+        Returns:
+            Tuple of (results, has_more, total_count) or None if not found
+        """
+        entry = self.get_by_cursor(cursor_id)
+        if not entry:
+            return None
+
+        total = len(entry.results)
+        page = entry.results[offset : offset + limit]
+        has_more = offset + limit < total
+
+        return page, has_more, total
+
+    def _evict_if_needed(self) -> None:
+        """Evict entries if cache is at capacity.
+
+        Uses LRU eviction strategy.
+        """
+        # First, remove expired entries
+        self.cleanup_expired()
+
+        # If still at capacity, evict LRU entries
+        while len(self._cache) >= self.max_entries:
+            # Find least recently used entry
+            lru_key = None
+            lru_time = float("inf")
+
+            for key, entry in self._cache.items():
+                if entry.last_accessed < lru_time:
+                    lru_time = entry.last_accessed
+                    lru_key = key
+
+            if lru_key:
+                entry = self._cache.pop(lru_key)
+                self._by_cursor.pop(entry.cursor_id, None)
+                logger.debug("Evicted LRU cache entry: %s", lru_key[1][:30])
+
+    def cleanup_expired(self) -> int:
+        """Remove all expired cache entries.
+
+        Returns:
+            Number of entries removed
+        """
+        with self._lock:
+            expired_keys = [
+                key for key, entry in self._cache.items() if entry.is_expired
+            ]
+
+            for key in expired_keys:
+                entry = self._cache.pop(key)
+                self._by_cursor.pop(entry.cursor_id, None)
+
+            if expired_keys:
+                logger.debug("Cleaned up %d expired cache entries", len(expired_keys))
+
+            return len(expired_keys)
+
+    def clear(self) -> None:
+        """Clear all cache entries."""
+        with self._lock:
+            self._cache.clear()
+            self._by_cursor.clear()
+            logger.debug("Cache cleared")
+
+    def stats(self) -> dict[str, Any]:
+        """Get cache statistics.
+
+        Returns:
+            Dictionary with cache statistics
+        """
+        with self._lock:
+            now = time.time()
+            entries = list(self._cache.values())
+
+            return {
+                "total_entries": len(entries),
+                "max_entries": self.max_entries,
+                "expired_entries": sum(1 for e in entries if e.is_expired),
+                "total_results_cached": sum(len(e.results) for e in entries),
+                "oldest_entry_age": (
+                    max(now - e.created_at for e in entries) if entries else 0
+                ),
+            }
+
+
+# Global cache instance
+_cache: SearchCache | None = None
+
+
+def get_cache() -> SearchCache:
+    """Get the global search cache instance.
+
+    Creates a new instance if none exists.
+    """
+    global _cache
+    if _cache is None:
+        _cache = SearchCache()
+    return _cache
+
+
+def reset_cache() -> None:
+    """Reset the global cache instance.
+
+    Useful for testing.
+    """
+    global _cache
+    if _cache:
+        _cache.clear()
+    _cache = None