PyStreamMCP 0.3.0__py3-none-any.whl

pystreammcp/__init__.py

@@ -0,0 +1,24 @@
+"""PyStreamMCP - Intelligence Layer for AI Agents."""
+
+__version__ = "0.3.0"
+__author__ = "Georgi Mammen Mullassery"
+
+from .core import (
+    MetadataIndex,
+    CapabilityDiscovery,
+    SchemaExtractor,
+    RelationshipGraph,
+    Metadata,
+    Capability,
+    Schema,
+)
+
+__all__ = [
+    "MetadataIndex",
+    "CapabilityDiscovery",
+    "SchemaExtractor",
+    "RelationshipGraph",
+    "Metadata",
+    "Capability",
+    "Schema",
+]

pystreammcp/api.py

@@ -0,0 +1,273 @@
+"""REST API for PyStreamMCP v0.3."""
+
+import json
+import sys
+from pathlib import Path
+from typing import Optional
+
+try:
+    from flask import Flask, jsonify, request, send_file
+    from flask_cors import CORS
+    HAS_FLASK = True
+except ImportError:
+    HAS_FLASK = False
+
+from pystreammcp.core import (
+    MetadataIndex,
+    CapabilityClassification,
+    Metadata,
+)
+from pystreammcp.persistence import SqlitePersistence
+from pystreammcp.routing import SemanticRouter, RoutingPlanner
+
+
+class StreamMCPAPI:
+    """REST API server for PyStreamMCP."""
+
+    def __init__(self, db_path: str = ":memory:", debug: bool = False):
+        """Initialize API."""
+        if not HAS_FLASK:
+            raise ImportError(
+                "Flask is required for the API. Install with: pip install flask flask-cors"
+            )
+
+        self.db_path = db_path
+        self.app = Flask(__name__)
+        self.app.config["JSON_SORT_KEYS"] = False
+        CORS(self.app)
+
+        self.index = MetadataIndex()
+        self.persistence = SqlitePersistence(db_path)
+        self.debug = debug
+
+        self._register_routes()
+
+    def _register_routes(self):
+        """Register API routes."""
+
+        @self.app.route("/health", methods=["GET"])
+        def health():
+            """Health check endpoint."""
+            return jsonify(
+                {
+                    "status": "ok",
+                    "version": "0.3.0",
+                    "db": "sqlite" if self.db_path != ":memory:" else "in-memory",
+                }
+            )
+
+        @self.app.route("/api/v1/metadata", methods=["POST"])
+        def index_tool():
+            """Index a new tool."""
+            data = request.json
+            try:
+                name = data.get("name")
+                description = data.get("description")
+                server_id = data.get("server_id")
+                tool_id = data.get("tool_id")
+                input_schema = data.get("input_schema", {})
+                output_schema = data.get("output_schema", {})
+
+                if not all([name, server_id, tool_id]):
+                    return jsonify({"error": "Missing required fields"}), 400
+
+                self.index.index_tool(
+                    name=name,
+                    description=description,
+                    server_id=server_id,
+                    tool_id=tool_id,
+                    input_schema=input_schema,
+                    output_schema=output_schema,
+                )
+
+                # Also persist to database
+                metadata = Metadata(
+                    name=name,
+                    description=description,
+                    server_id=server_id,
+                    tool_id=tool_id,
+                    input_schema=input_schema,
+                    output_schema=output_schema,
+                )
+                self.persistence.insert_metadata(metadata)
+
+                return jsonify(
+                    {
+                        "status": "success",
+                        "message": f"Tool {name} indexed",
+                        "metadata_id": metadata.id,
+                    }
+                )
+            except Exception as e:
+                return jsonify({"error": str(e)}), 500
+
+        @self.app.route("/api/v1/search", methods=["GET"])
+        def search():
+            """Search for tools."""
+            query = request.args.get("q", "")
+            limit = int(request.args.get("limit", 10))
+
+            if not query:
+                return jsonify({"error": "Missing query parameter"}), 400
+
+            results = self.index.search_by_name(query)[:limit]
+
+            return jsonify(
+                {
+                    "query": query,
+                    "count": len(results),
+                    "results": [
+                        {
+                            "id": m.id,
+                            "name": m.name,
+                            "description": m.description,
+                            "server_id": m.server_id,
+                            "tool_id": m.tool_id,
+                        }
+                        for m in results
+                    ],
+                }
+            )
+
+        @self.app.route("/api/v1/route", methods=["POST"])
+        def route_query():
+            """Route a query to optimal tools."""
+            data = request.json
+            try:
+                query = data.get("query")
+                max_tools = int(data.get("max_tools", 3))
+
+                if not query:
+                    return jsonify({"error": "Missing query parameter"}), 400
+
+                all_metadata = self.index.get_all_metadata()
+                capabilities_map = {}
+
+                for metadata in all_metadata:
+                    caps = self.index.capability_discovery.get_by_metadata(
+                        metadata.id
+                    )
+                    capabilities_map[metadata.id] = caps
+
+                scores = SemanticRouter.rank_tools(query, all_metadata, capabilities_map)
+                plan = RoutingPlanner.plan(query, scores, max_tools)
+
+                return jsonify(plan.to_dict())
+            except Exception as e:
+                return jsonify({"error": str(e)}), 500
+
+        @self.app.route("/api/v1/stats", methods=["GET"])
+        def stats():
+            """Get index statistics."""
+            stats_data = self.index.stats()
+            return jsonify(
+                {
+                    "total_metadata": stats_data["total_metadata"],
+                    "total_capabilities": stats_data["total_capabilities"],
+                    "total_schemas": stats_data["total_schemas"],
+                    "total_relationships": stats_data["total_relationships"],
+                    "db_entries": self.persistence.count_metadata(),
+                }
+            )
+
+        @self.app.route("/api/v1/metadata/<metadata_id>", methods=["GET"])
+        def get_metadata(metadata_id):
+            """Get specific metadata."""
+            metadata = self.index.get_all_metadata()
+            for m in metadata:
+                if m.id == metadata_id or m.tool_id == metadata_id:
+                    caps = self.index.capability_discovery.get_by_metadata(m.id)
+                    return jsonify(
+                        {
+                            "id": m.id,
+                            "name": m.name,
+                            "description": m.description,
+                            "server_id": m.server_id,
+                            "tool_id": m.tool_id,
+                            "capabilities": [
+                                {
+                                    "classification": c.classification.value,
+                                    "inputs": c.inputs,
+                                    "outputs": c.outputs,
+                                }
+                                for c in caps
+                            ],
+                        }
+                    )
+
+            return jsonify({"error": "Not found"}), 404
+
+        @self.app.route("/api/v1/capabilities", methods=["GET"])
+        def get_capabilities():
+            """Get capabilities by type."""
+            classification = request.args.get("type", "search")
+
+            try:
+                cap_class = CapabilityClassification[classification.title()]
+                caps = self.index.get_capabilities_by_classification(cap_class)
+
+                return jsonify(
+                    {
+                        "type": classification,
+                        "count": len(caps),
+                        "capabilities": [
+                            {
+                                "id": c.id,
+                                "metadata_id": c.metadata_id,
+                                "inputs": c.inputs,
+                                "outputs": c.outputs,
+                                "cost": c.cost_estimate,
+                            }
+                            for c in caps
+                        ],
+                    }
+                )
+            except KeyError:
+                return jsonify({"error": f"Unknown type: {classification}"}), 400
+
+        @self.app.route("/api/v1/servers", methods=["GET"])
+        def get_servers():
+            """Get all unique servers."""
+            servers = {}
+            for metadata in self.index.get_all_metadata():
+                if metadata.server_id not in servers:
+                    servers[metadata.server_id] = 0
+                servers[metadata.server_id] += 1
+
+            return jsonify({"servers": servers})
+
+        @self.app.errorhandler(404)
+        def not_found(error):
+            """404 handler."""
+            return jsonify({"error": "Not found"}), 404
+
+        @self.app.errorhandler(500)
+        def server_error(error):
+            """500 handler."""
+            return jsonify({"error": "Internal server error"}), 500
+
+    def run(self, host: str = "0.0.0.0", port: int = 8011, debug: bool = False):
+        """Run the API server."""
+        print(f"[*] StreamMCP API v0.3 running on {host}:{port}")
+        print(f"[*] Database: {self.db_path}")
+        print(f"[*] Endpoints: /health, /api/v1/search, /api/v1/route, /api/v1/stats")
+        self.app.run(host=host, port=port, debug=debug, threaded=True)
+
+    def close(self):
+        """Close resources."""
+        self.persistence.close()
+
+
+def create_app(db_path: str = ":memory:") -> Flask:
+    """Create Flask app."""
+    api = StreamMCPAPI(db_path)
+    return api.app
+
+
+def run_server(db_path: Optional[str] = None, port: int = 8011):
+    """Run the REST API server."""
+    if db_path is None:
+        db_path = ":memory:"
+
+    api = StreamMCPAPI(db_path)
+    api.run(port=port, debug=False)

pystreammcp/cli.py

@@ -0,0 +1,385 @@
+"""CLI for PyStreamMCP v0.3 - Metadata Indexing & Routing."""
+
+import json
+import sys
+from pathlib import Path
+from typing import Optional
+
+import click
+from rich.console import Console
+from rich.table import Table
+from rich.panel import Panel
+from rich.syntax import Syntax
+
+from pystreammcp.core import (
+    MetadataIndex,
+    CapabilityClassification,
+    RelationType,
+    Metadata,
+)
+
+console = Console()
+
+
+class Context:
+    """CLI context for state management."""
+
+    def __init__(self):
+        self.index = MetadataIndex()
+
+
+pass_context = click.make_pass_decorator(Context)
+
+
+@click.group()
+@click.pass_context
+def cli(ctx):
+    """StreamMCP v0.2 - Intelligence Layer for MCP Systems.
+
+    Discover, index, and intelligently route queries across MCP servers.
+    """
+    ctx.obj = Context()
+
+
+@cli.command()
+@click.option("--file", "-f", type=click.Path(exists=True), help="Load tools from JSON file")
+@click.option("--format", "-fmt", type=click.Choice(["json", "csv"]), default="json")
+@pass_context
+def discover(ctx: Context, file: Optional[str], format: str):
+    """Discover MCP servers and tools.
+
+    Scans connected MCP servers and catalogs available tools.
+    """
+    console.print("[bold cyan]🔍 MCP Server Discovery[/bold cyan]")
+
+    if file:
+        try:
+            with open(file) as f:
+                data = json.load(f)
+                tools = data.get("tools", [])
+                console.print(f"[green]✓[/green] Loaded {len(tools)} tools from {file}")
+
+                # Index tools
+                result = ctx.index.bulk_index_tools(tools)
+                console.print(f"\n[bold]Indexing Results:[/bold]")
+                console.print(f"  Total: {result['total']}")
+                console.print(f"  Success: [green]{result['success']}[/green]")
+                console.print(f"  Errors: [red]{result['errors']}[/red]")
+                console.print(f"  Duration: {result['duration_ms']}ms")
+
+                # Show stats
+                stats = ctx.index.stats()
+                console.print(f"\n[bold]Index Statistics:[/bold]")
+                console.print(f"  Metadata entries: {stats['total_metadata']}")
+                console.print(f"  Capabilities: {stats['total_capabilities']}")
+                console.print(f"  Schemas: {stats['total_schemas']}")
+                console.print(f"  Relationships: {stats['total_relationships']}")
+        except FileNotFoundError:
+            console.print(f"[red]✗ File not found: {file}[/red]", file=sys.stderr)
+            sys.exit(1)
+    else:
+        console.print(
+            "[yellow]⚠ Mock discovery (provide --file for real tools)[/yellow]"
+        )
+        console.print("\n[bold]Available Servers:[/bold]")
+        console.print("  • web_server (4 tools)")
+        console.print("  • file_server (3 tools)")
+        console.print("  • database_server (5 tools)")
+        console.print("  • github_server (8 tools)")
+
+
+@cli.command()
+@click.argument("query")
+@click.option("--classification", "-c", help="Filter by capability classification")
+@click.option("--server", "-s", help="Filter by server")
+@click.option("--limit", "-l", type=int, default=10, help="Max results")
+@pass_context
+def search(ctx: Context, query: str, classification: Optional[str], server: Optional[str], limit: int):
+    """Search for tools by name or description.
+
+    Find relevant tools using intelligent metadata search.
+    """
+    console.print(f"[bold cyan]🔎 Searching: '{query}'[/bold cyan]\n")
+
+    results = ctx.index.search_by_name(query)
+
+    if classification:
+        try:
+            cap_class = CapabilityClassification[classification.title()]
+            results = [
+                m
+                for m in results
+                if any(
+                    c.classification == cap_class
+                    for c in ctx.index.capability_discovery.get_by_metadata(m.id)
+                )
+            ]
+        except KeyError:
+            console.print(f"[red]Unknown classification: {classification}[/red]", file=sys.stderr)
+            sys.exit(1)
+
+    if server:
+        results = [m for m in results if m.server_id == server]
+
+    results = results[:limit]
+
+    if not results:
+        console.print("[yellow]No tools found matching your search.[/yellow]")
+        return
+
+    # Show results table
+    table = Table(title=f"Search Results ({len(results)})", show_header=True)
+    table.add_column("Tool", style="cyan")
+    table.add_column("Server", style="magenta")
+    table.add_column("Description")
+    table.add_column("Type", style="yellow")
+
+    for metadata in results:
+        capabilities = ctx.index.capability_discovery.get_by_metadata(metadata.id)
+        cap_type = (
+            capabilities[0].classification.value if capabilities else "unknown"
+        )
+        table.add_row(
+            metadata.name,
+            metadata.server_id,
+            metadata.description[:50] + "..."
+            if len(metadata.description) > 50
+            else metadata.description,
+            cap_type,
+        )
+
+    console.print(table)
+
+
+@cli.command()
+@click.argument("tool_id")
+@pass_context
+def inspect(ctx: Context, tool_id: str):
+    """Inspect a specific tool in detail.
+
+    Show full metadata, schema, capabilities, and relationships.
+    """
+    # Search for the tool
+    all_metadata = ctx.index.get_all_metadata()
+    metadata = None
+    for m in all_metadata:
+        if m.tool_id == tool_id or m.name == tool_id or m.id == tool_id:
+            metadata = m
+            break
+
+    if not metadata:
+        console.print(f"[red]✗ Tool not found: {tool_id}[/red]", file=sys.stderr)
+        sys.exit(1)
+
+    console.print(f"\n[bold cyan]📋 Tool: {metadata.name}[/bold cyan]\n")
+
+    # Basic info
+    info = Panel(
+        f"[cyan]ID:[/cyan] {metadata.id}\n"
+        f"[cyan]Server:[/cyan] {metadata.server_id}\n"
+        f"[cyan]Tool ID:[/cyan] {metadata.tool_id}\n"
+        f"[cyan]Description:[/cyan] {metadata.description}",
+        title="Basic Info",
+    )
+    console.print(info)
+
+    # Capabilities
+    capabilities = ctx.index.capability_discovery.get_by_metadata(metadata.id)
+    if capabilities:
+        cap_text = "\n".join(
+            [
+                f"[yellow]{c.classification.value}[/yellow] "
+                f"(cost: ${c.cost_estimate:.2f}, latency: {c.latency_estimate_ms}ms)"
+                for c in capabilities
+            ]
+        )
+        cap_panel = Panel(cap_text, title="Capabilities")
+        console.print(cap_panel)
+
+    # Schema
+    schemas = ctx.index.get_tool_schema(metadata.id)
+    if schemas:
+        schema_panel = Panel(
+            json.dumps([asdict(s) for s in schemas], indent=2, default=str),
+            title="Schemas",
+        )
+        console.print(schema_panel)
+
+
+@cli.command()
+@click.option("--server", "-s", help="Filter by server")
+@pass_context
+def stats(ctx: Context, server: Optional[str]):
+    """Show metadata index statistics.
+
+    Display overall indexing statistics and distribution.
+    """
+    console.print("[bold cyan]📊 Index Statistics[/bold cyan]\n")
+
+    stats_data = ctx.index.stats()
+
+    # Overall stats
+    table = Table(show_header=False)
+    table.add_row("Total Metadata", f"[cyan]{stats_data['total_metadata']}[/cyan]")
+    table.add_row("Total Capabilities", f"[green]{stats_data['total_capabilities']}[/green]")
+    table.add_row("Total Schemas", f"[yellow]{stats_data['total_schemas']}[/yellow]")
+    table.add_row(
+        "Total Relationships", f"[magenta]{stats_data['total_relationships']}[/magenta]"
+    )
+    console.print(table)
+
+    # Capability distribution
+    console.print("\n[bold]Capability Distribution:[/bold]")
+    for classification in CapabilityClassification:
+        if classification == CapabilityClassification.Unknown:
+            continue
+        count = len(ctx.index.get_capabilities_by_classification(classification))
+        bar = "█" * (count // 2)
+        console.print(f"  {classification.value:12} {bar} ({count})")
+
+    # Server distribution
+    if not server:
+        console.print("\n[bold]Servers:[/bold]")
+        servers: dict = {}
+        for metadata in ctx.index.get_all_metadata():
+            servers[metadata.server_id] = servers.get(metadata.server_id, 0) + 1
+        for srv, count in sorted(servers.items()):
+            console.print(f"  {srv}: {count} tools")
+
+
+@cli.command()
+@click.argument("name")
+@click.argument("description")
+@click.option("--server", "-s", required=True, help="Server ID")
+@click.option("--tool-id", "-t", required=True, help="Tool ID")
+@click.option("--input-schema", "-i", type=click.Path(exists=True), help="Input schema JSON file")
+@click.option("--output-schema", "-o", type=click.Path(exists=True), help="Output schema JSON file")
+@pass_context
+def index(ctx: Context, name: str, description: str, server: str, tool_id: str, input_schema: Optional[str], output_schema: Optional[str]):
+    """Index a new tool.
+
+    Add a tool to the metadata index.
+    """
+    console.print(f"[bold cyan]📝 Indexing Tool: {name}[/bold cyan]\n")
+
+    # Load schemas
+    input_json = {}
+    output_json = {}
+
+    if input_schema:
+        try:
+            with open(input_schema) as f:
+                input_json = json.load(f)
+        except FileNotFoundError:
+            console.print(f"[red]Input schema file not found: {input_schema}[/red]", file=sys.stderr)
+            sys.exit(1)
+
+    if output_schema:
+        try:
+            with open(output_schema) as f:
+                output_json = json.load(f)
+        except FileNotFoundError:
+            console.print(f"[red]Output schema file not found: {output_schema}[/red]", file=sys.stderr)
+            sys.exit(1)
+
+    # Index
+    try:
+        ctx.index.index_tool(
+            name=name,
+            description=description,
+            server_id=server,
+            tool_id=tool_id,
+            input_schema=input_json,
+            output_schema=output_json,
+        )
+        console.print("[green]✓[/green] Tool indexed successfully")
+        stats = ctx.index.stats()
+        console.print(f"[dim]Index now contains {stats['total_metadata']} tools[/dim]")
+    except Exception as e:
+        console.print(f"[red]✗ Indexing failed: {e}[/red]", file=sys.stderr)
+        sys.exit(1)
+
+
+@cli.command()
+@click.option("--capabilities", "-c", is_flag=True, help="Show capability details")
+@click.option("--schemas", "-s", is_flag=True, help="Show schema details")
+@pass_context
+def list_tools(ctx: Context, capabilities: bool, schemas: bool):
+    """List all indexed tools.
+
+    Display all tools currently in the index.
+    """
+    all_metadata = ctx.index.get_all_metadata()
+
+    if not all_metadata:
+        console.print("[yellow]No tools indexed.[/yellow]")
+        return
+
+    console.print(f"[bold cyan]📚 Indexed Tools ({len(all_metadata)})[/bold cyan]\n")
+
+    table = Table(show_header=True)
+    table.add_column("Name", style="cyan")
+    table.add_column("Server", style="magenta")
+    table.add_column("Type", style="yellow")
+    table.add_column("Capabilities", style="green")
+
+    for metadata in all_metadata:
+        caps = ctx.index.capability_discovery.get_by_metadata(metadata.id)
+        cap_types = ", ".join([c.classification.value for c in caps])
+        table.add_row(
+            metadata.name,
+            metadata.server_id,
+            metadata.tool_id,
+            cap_types or "unknown",
+        )
+
+    console.print(table)
+
+    if capabilities:
+        console.print("\n[bold]Capability Details:[/bold]")
+        for metadata in all_metadata:
+            caps = ctx.index.capability_discovery.get_by_metadata(metadata.id)
+            if caps:
+                console.print(f"\n  {metadata.name}:")
+                for cap in caps:
+                    console.print(
+                        f"    • {cap.classification.value} "
+                        f"(inputs: {len(cap.inputs)}, outputs: {len(cap.outputs)})"
+                    )
+
+    if schemas:
+        console.print("\n[bold]Schemas:[/bold]")
+        for metadata in all_metadata:
+            schemas = ctx.index.get_tool_schema(metadata.id)
+            if schemas:
+                console.print(f"\n  {metadata.name}:")
+                for schema in schemas:
+                    console.print(f"    • {schema.base_type.value} (props: {len(schema.properties)})")
+
+
+@cli.command()
+@pass_context
+def version(ctx: Context):
+    """Show version information."""
+    from streammcp import __version__
+
+    console.print(f"[bold]StreamMCP[/bold] v{__version__}")
+    console.print("[dim]Intelligence Layer for MCP Systems[/dim]")
+    console.print(f"\nPhase: v0.2 - Metadata-First Architecture")
+    console.print("Status: [yellow]In Development[/yellow]")
+
+
+def main():
+    """Entry point."""
+    try:
+        cli()
+    except KeyboardInterrupt:
+        console.print("\n[yellow]Cancelled[/yellow]")
+        sys.exit(0)
+    except Exception as e:
+        console.print(f"[red]Error: {e}[/red]", file=sys.stderr)
+        sys.exit(1)
+
+
+if __name__ == "__main__":
+    main()