piercloud-mcp 0.1.0__tar.gz

piercloud_mcp-0.1.0/PKG-INFO

@@ -0,0 +1,106 @@
+Metadata-Version: 2.1
+Name: piercloud-mcp
+Version: 0.1.0
+Summary: A scalable MCP server with clean architecture
+Home-page: https://github.com/piercloud/piercloud-mcp
+License: MIT
+Keywords: mcp,model-context-protocol,ai,llm
+Author: Pier Team
+Author-email: engineering@piercloud.com
+Requires-Python: >=3.10,<4.0
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Requires-Dist: httpx (>=0.27.0,<0.28.0)
+Requires-Dist: mcp (>=1.0.0,<2.0.0)
+Requires-Dist: pydantic (>=2.0.0,<3.0.0)
+Requires-Dist: starlette (>=0.37.0,<0.38.0)
+Requires-Dist: uvicorn (>=0.30.0,<0.31.0)
+Project-URL: Repository, https://github.com/piercloud/piercloud-mcp
+Description-Content-Type: text/markdown
+
+# Pier Cloud MCP Server
+
+A scalable Model Context Protocol server with clean architecture.
+
+## Quick Start
+
+```bash
+# Setup
+poetry install
+
+# Local mode (stdio)
+poetry run piercloud-mcp
+
+# Production mode (HTTP/SSE)
+poetry run piercloud-mcp --sse --port 8000
+```
+
+## Production Deployment
+
+Deploy as HTTP server at `https://mcp.piercloud.io`:
+
+```bash
+# Run server
+poetry run piercloud-mcp --sse --port 8000
+```
+
+### MCP Protocol (Claude, Cline, etc)
+```json
+{
+  "mcpServers": {
+    "pier": {
+      "url": "https://mcp.piercloud.io/mcp/sse"
+    }
+  }
+}
+```
+
+### REST API (ChatGPT, Gemini, any LLM)
+```bash
+# List tools
+curl https://mcp.piercloud.io/api/tools
+
+# Execute tool
+curl -X POST https://mcp.piercloud.io/api/tools/echo \
+  -H "Content-Type: application/json" \
+  -d '{"message": "hello", "uppercase": true}'
+
+# OpenAPI spec
+curl https://mcp.piercloud.io/openapi.json
+```
+
+## Adding Tools
+
+Create a new file in `src/pier_mcp/tools/` and register:
+
+```python
+from pydantic import BaseModel, Field
+
+class MyToolInput(BaseModel):
+    param: str = Field(description="Parameter description")
+
+def register_my_tools(mcp):
+    @mcp.tool("my_tool", "Tool description", MyToolInput)
+    async def my_tool(args: MyToolInput) -> str:
+        return f"Result: {args.param}"
+```
+
+Then import in `main.py`:
+
+```python
+from pier_mcp.tools.my_tools import register_my_tools
+register_my_tools(mcp)
+```
+
+## Architecture
+
+- `server.py` - Core MCP server with tool registry
+- `tools/` - Tool implementations (one file per domain)
+- `main.py` - Entry point and tool registration
+
+Clean, minimal, scalable.
+

piercloud_mcp-0.1.0/README.md

@@ -0,0 +1,81 @@
+# Pier Cloud MCP Server
+
+A scalable Model Context Protocol server with clean architecture.
+
+## Quick Start
+
+```bash
+# Setup
+poetry install
+
+# Local mode (stdio)
+poetry run piercloud-mcp
+
+# Production mode (HTTP/SSE)
+poetry run piercloud-mcp --sse --port 8000
+```
+
+## Production Deployment
+
+Deploy as HTTP server at `https://mcp.piercloud.io`:
+
+```bash
+# Run server
+poetry run piercloud-mcp --sse --port 8000
+```
+
+### MCP Protocol (Claude, Cline, etc)
+```json
+{
+  "mcpServers": {
+    "pier": {
+      "url": "https://mcp.piercloud.io/mcp/sse"
+    }
+  }
+}
+```
+
+### REST API (ChatGPT, Gemini, any LLM)
+```bash
+# List tools
+curl https://mcp.piercloud.io/api/tools
+
+# Execute tool
+curl -X POST https://mcp.piercloud.io/api/tools/echo \
+  -H "Content-Type: application/json" \
+  -d '{"message": "hello", "uppercase": true}'
+
+# OpenAPI spec
+curl https://mcp.piercloud.io/openapi.json
+```
+
+## Adding Tools
+
+Create a new file in `src/pier_mcp/tools/` and register:
+
+```python
+from pydantic import BaseModel, Field
+
+class MyToolInput(BaseModel):
+    param: str = Field(description="Parameter description")
+
+def register_my_tools(mcp):
+    @mcp.tool("my_tool", "Tool description", MyToolInput)
+    async def my_tool(args: MyToolInput) -> str:
+        return f"Result: {args.param}"
+```
+
+Then import in `main.py`:
+
+```python
+from pier_mcp.tools.my_tools import register_my_tools
+register_my_tools(mcp)
+```
+
+## Architecture
+
+- `server.py` - Core MCP server with tool registry
+- `tools/` - Tool implementations (one file per domain)
+- `main.py` - Entry point and tool registration
+
+Clean, minimal, scalable.

piercloud_mcp-0.1.0/pyproject.toml

@@ -0,0 +1,34 @@
+[tool.poetry]
+name = "piercloud-mcp"
+version = "0.1.0"
+description = "A scalable MCP server with clean architecture"
+authors = ["Pier Team <engineering@piercloud.com>"]
+readme = "README.md"
+license = "MIT"
+homepage = "https://github.com/piercloud/piercloud-mcp"
+repository = "https://github.com/piercloud/piercloud-mcp"
+keywords = ["mcp", "model-context-protocol", "ai", "llm"]
+packages = [{include = "pier_mcp", from = "src"}]
+
+[tool.poetry.dependencies]
+python = "^3.10"
+mcp = "^1.0.0"
+pydantic = "^2.0.0"
+uvicorn = "^0.30.0"
+starlette = "^0.37.0"
+httpx = "^0.27.0"
+
+[tool.poetry.group.dev.dependencies]
+pytest = "^7.0.0"
+ruff = "^0.1.0"
+
+[tool.poetry.scripts]
+piercloud-mcp = "pier_mcp.main:main"
+
+[build-system]
+requires = ["poetry-core"]
+build-backend = "poetry.core.masonry.api"
+
+[tool.ruff]
+line-length = 100
+target-version = "py310"

piercloud_mcp-0.1.0/src/pier_mcp/__init__.py

@@ -0,0 +1,3 @@
+"""Pier MCP Server - A scalable Model Context Protocol server."""
+
+__version__ = "0.1.0"

piercloud_mcp-0.1.0/src/pier_mcp/client.py

@@ -0,0 +1,81 @@
+"""HTTP client for Pier Cloud API."""
+
+import os
+import httpx
+from typing import Any, Optional
+from datetime import datetime, timedelta
+
+
+class PierCloudClient:
+    """Client for Pier Cloud API with JWT authentication."""
+
+    def __init__(self):
+        self.base_url = os.getenv("PIERCLOUD_API_URL", "https://api.piercloud.io/lake")
+        self.client_id = os.getenv("PIERCLOUD_CLIENT_ID")
+        self.client_secret = os.getenv("PIERCLOUD_CLIENT_SECRET")
+
+        if not self.client_id or not self.client_secret:
+            raise ValueError(
+                "PIERCLOUD_CLIENT_ID and PIERCLOUD_CLIENT_SECRET are required. "
+                "Set them as environment variables."
+            )
+
+        self.client = httpx.AsyncClient(base_url=self.base_url, timeout=30.0)
+        self.access_token: Optional[str] = None
+        self.token_expires_at: Optional[datetime] = None
+
+    async def _authenticate(self):
+        """Authenticate and get JWT token."""
+        response = await self.client.post(
+            "https://api.piercloud.io/auth",
+            json={"client_id": self.client_id, "client_secret": self.client_secret},
+        )
+        response.raise_for_status()
+
+        data = response.json()["data"]
+        self.access_token = data["access_token"]
+
+        # Set expiration (with 60s buffer)
+        expires_in = data["expires_in"] - 60
+        self.token_expires_at = datetime.now() + timedelta(seconds=expires_in)
+
+    async def _ensure_authenticated(self):
+        """Ensure we have a valid token."""
+        if not self.access_token or not self.token_expires_at:
+            await self._authenticate()
+        elif datetime.now() >= self.token_expires_at:
+            await self._authenticate()
+
+    async def get(self, path: str) -> Any:
+        """GET request with authentication."""
+        await self._ensure_authenticated()
+        response = await self.client.get(
+            path, headers={"Authorization": f"Bearer {self.access_token}"}
+        )
+        response.raise_for_status()
+        return response.json()
+
+    async def post(self, path: str, data: dict) -> Any:
+        """POST request with authentication."""
+        await self._ensure_authenticated()
+        response = await self.client.post(
+            path, json=data, headers={"Authorization": f"Bearer {self.access_token}"}
+        )
+        response.raise_for_status()
+        return response.json()
+
+    async def close(self):
+        """Close client."""
+        await self.client.aclose()
+
+
+# Singleton instance
+_client = None
+
+
+def get_client() -> PierCloudClient:
+    """Get or create client instance."""
+    global _client
+    if _client is None:
+        _client = PierCloudClient()
+    return _client

piercloud_mcp-0.1.0/src/pier_mcp/main.py

@@ -0,0 +1,35 @@
+"""MCP server entry point - register your tools here."""
+
+import asyncio
+import sys
+import uvicorn
+from pier_mcp.server import MCPServer
+from pier_mcp.sse_server import create_sse_server
+from pier_mcp.tools.rebilling import register_rebilling_tools
+from pier_mcp import __version__
+
+
+# Initialize server
+mcp = MCPServer("piercloud-mcp-server", __version__)
+
+# Register tools
+register_rebilling_tools(mcp)
+
+
+def main():
+    """Run the MCP server."""
+    if "--sse" in sys.argv:
+        # Production mode: HTTP server
+        port = 8000
+        if "--port" in sys.argv:
+            port = int(sys.argv[sys.argv.index("--port") + 1])
+
+        app = create_sse_server(mcp)
+        uvicorn.run(app, host="0.0.0.0", port=port)
+    else:
+        # Local mode: stdio
+        asyncio.run(mcp.run())
+
+
+if __name__ == "__main__":
+    main()

piercloud_mcp-0.1.0/src/pier_mcp/rest_api.py

@@ -0,0 +1,112 @@
+"""REST API layer for universal LLM integration."""
+
+from starlette.routing import Route
+from starlette.responses import JSONResponse
+from starlette.requests import Request
+
+
+def create_rest_routes(mcp_server):
+    """Create REST API routes that reuse the existing ToolRegistry."""
+
+    async def list_tools(request: Request):
+        """GET /api/tools - List all available tools."""
+        tools = []
+        for name, config in mcp_server.registry._tools.items():
+            tool_def = {
+                "name": name,
+                "description": config["description"],
+            }
+            if config["schema"]:
+                tool_def["parameters"] = config["schema"].model_json_schema()
+            tools.append(tool_def)
+
+        return JSONResponse({"tools": tools})
+
+    async def execute_tool(request: Request):
+        """POST /api/tools/{name} - Execute a tool."""
+        tool_name = request.path_params["name"]
+        body = await request.json()
+
+        try:
+            result = await mcp_server.registry.execute(tool_name, body)
+            return JSONResponse({"success": True, "result": result[0].text})
+        except Exception as e:
+            return JSONResponse({"success": False, "error": str(e)}, status_code=400)
+
+    async def openapi_spec(request: Request):
+        """GET /openapi.json - OpenAPI specification."""
+        paths = {}
+
+        for name, config in mcp_server.registry._tools.items():
+            schema = {}
+            if config["schema"]:
+                schema = config["schema"].model_json_schema()
+
+            paths[f"/api/tools/{name}"] = {
+                "post": {
+                    "summary": config["description"],
+                    "requestBody": {
+                        "content": {"application/json": {"schema": schema}}
+                    },
+                    "responses": {
+                        "200": {
+                            "description": "Success",
+                            "content": {
+                                "application/json": {
+                                    "schema": {
+                                        "type": "object",
+                                        "properties": {
+                                            "success": {"type": "boolean"},
+                                            "result": {"type": "string"},
+                                        },
+                                    }
+                                }
+                            },
+                        }
+                    },
+                }
+            }
+
+        spec = {
+            "openapi": "3.0.0",
+            "info": {
+                "title": "Pier Cloud MCP Server",
+                "version": mcp_server.version,
+                "description": "Universal tool server for any LLM",
+            },
+            "servers": [{"url": "https://mcp.piercloud.io"}],
+            "paths": {
+                "/api/tools": {
+                    "get": {
+                        "summary": "List all tools",
+                        "responses": {
+                            "200": {
+                                "description": "List of tools",
+                                "content": {
+                                    "application/json": {
+                                        "schema": {
+                                            "type": "object",
+                                            "properties": {
+                                                "tools": {
+                                                    "type": "array",
+                                                    "items": {"type": "object"},
+                                                }
+                                            },
+                                        }
+                                    }
+                                },
+                            }
+                        },
+                    }
+                },
+                **paths,
+            },
+        }
+
+        return JSONResponse(spec)
+
+    return [
+        Route("/api/tools", endpoint=list_tools),
+        Route("/api/tools/{name}", endpoint=execute_tool, methods=["POST"]),
+        Route("/openapi.json", endpoint=openapi_spec),
+    ]

piercloud_mcp-0.1.0/src/pier_mcp/server.py

@@ -0,0 +1,104 @@
+"""Core MCP server implementation with tool registry."""
+
+from typing import Any, Callable
+from mcp.server import Server
+from mcp.server.stdio import stdio_server
+from mcp.types import Tool, TextContent
+from pydantic import BaseModel
+
+
+class ToolRegistry:
+    """Manages tool registration and execution with automatic schema generation."""
+    
+    def __init__(self):
+        self._tools: dict[str, dict[str, Any]] = {}
+    
+    def tool(
+        self,
+        name: str,
+        description: str,
+        schema: type[BaseModel] | None = None
+    ):
+        """Decorator to register a tool with automatic schema validation.
+        
+        Usage:
+            @registry.tool("tool_name", "Description", InputSchema)
+            async def my_tool(args: InputSchema) -> str:
+                return "result"
+        """
+        def decorator(func: Callable) -> Callable:
+            self._tools[name] = {
+                "description": description,
+                "schema": schema,
+                "handler": func,
+            }
+            return func
+        return decorator
+    
+    def get_tool_definitions(self) -> list[Tool]:
+        """Generate MCP tool definitions from registered tools."""
+        tools = []
+        for name, config in self._tools.items():
+            input_schema = {}
+            if config["schema"]:
+                input_schema = config["schema"].model_json_schema()
+            
+            tools.append(Tool(
+                name=name,
+                description=config["description"],
+                inputSchema=input_schema,
+            ))
+        return tools
+    
+    async def execute(self, name: str, arguments: dict[str, Any]) -> list[TextContent]:
+        """Execute a registered tool with validation."""
+        if name not in self._tools:
+            raise ValueError(f"Tool '{name}' not found")
+        
+        config = self._tools[name]
+        
+        # Validate and parse arguments if schema exists
+        if config["schema"]:
+            args = config["schema"](**arguments)
+        else:
+            args = arguments
+        
+        # Execute handler
+        result = await config["handler"](args)
+        
+        return [TextContent(type="text", text=str(result))]
+
+
+class MCPServer:
+    """Main MCP server with tool registry."""
+    
+    def __init__(self, name: str, version: str):
+        self.server = Server(name)
+        self.registry = ToolRegistry()
+        self.name = name
+        self.version = version
+        self._setup_handlers()
+    
+    def _setup_handlers(self):
+        """Configure MCP protocol handlers."""
+        
+        @self.server.list_tools()
+        async def list_tools() -> list[Tool]:
+            return self.registry.get_tool_definitions()
+        
+        @self.server.call_tool()
+        async def call_tool(name: str, arguments: dict[str, Any]) -> list[TextContent]:
+            return await self.registry.execute(name, arguments)
+    
+    def tool(self, name: str, description: str, schema: type[BaseModel] | None = None):
+        """Register a tool (delegates to registry)."""
+        return self.registry.tool(name, description, schema)
+    
+    async def run(self):
+        """Start the MCP server."""
+        async with stdio_server() as (read_stream, write_stream):
+            await self.server.run(
+                read_stream,
+                write_stream,
+                self.server.create_initialization_options()
+            )

piercloud_mcp-0.1.0/src/pier_mcp/sse_server.py

@@ -0,0 +1,41 @@
+"""SSE server for production deployment."""
+
+from mcp.server.sse import SseServerTransport
+from starlette.applications import Starlette
+from starlette.routing import Route
+from starlette.responses import Response
+from pier_mcp.rest_api import create_rest_routes
+
+
+def create_sse_server(mcp_server):
+    """Create Starlette app with SSE transport and REST API."""
+    
+    sse = SseServerTransport("/mcp/sse")
+    
+    async def handle_sse(request):
+        async with sse.connect_sse(
+            request.scope,
+            request.receive,
+            request._send,
+        ) as streams:
+            await mcp_server.server.run(
+                streams[0],
+                streams[1],
+                mcp_server.server.create_initialization_options(),
+            )
+        return Response()
+    
+    async def handle_messages(request):
+        await sse.handle_post_message(request.scope, request.receive, request._send)
+        return Response()
+    
+    # Combine MCP and REST routes
+    routes = [
+        Route("/mcp/sse", endpoint=handle_sse),
+        Route("/mcp/messages", endpoint=handle_messages, methods=["POST"]),
+        *create_rest_routes(mcp_server),
+    ]
+    
+    app = Starlette(routes=routes)
+    
+    return app

piercloud_mcp-0.1.0/src/pier_mcp/tools/__init__.py

@@ -0,0 +1,3 @@
+"""Tool implementations - add your tools here."""
+
+# Import and register tools in main.py

piercloud_mcp-0.1.0/src/pier_mcp/tools/example.py

@@ -0,0 +1,30 @@
+"""Example tools demonstrating the registration pattern."""
+
+from pydantic import BaseModel, Field
+
+
+class EchoInput(BaseModel):
+    """Input schema for echo tool."""
+    message: str = Field(description="Message to echo back")
+    uppercase: bool = Field(default=False, description="Return in uppercase")
+
+
+class AddInput(BaseModel):
+    """Input schema for add tool."""
+    a: float = Field(description="First number")
+    b: float = Field(description="Second number")
+
+
+def register_example_tools(mcp):
+    """Register example tools to demonstrate the pattern."""
+    
+    @mcp.tool("echo", "Echoes a message back, optionally in uppercase", EchoInput)
+    async def echo(args: EchoInput) -> str:
+        result = args.message
+        if args.uppercase:
+            result = result.upper()
+        return result
+    
+    @mcp.tool("add", "Adds two numbers together", AddInput)
+    async def add(args: AddInput) -> str:
+        return str(args.a + args.b)

piercloud_mcp-0.1.0/src/pier_mcp/tools/rebilling.py

@@ -0,0 +1,65 @@
+"""Rebilling tools for querying cloud cost data."""
+
+from pydantic import BaseModel, Field
+from pier_mcp.client import get_client
+
+
+class GetSchemaInput(BaseModel):
+    """Input for get_rebilling_schema tool."""
+
+    provider: str = Field(description="Cloud provider: 'aws', 'azure', or 'gcp'")
+
+
+class QueryRebillingInput(BaseModel):
+    """Input for query_rebilling tool."""
+
+    provider: str = Field(description="Cloud provider: 'aws', 'azure', or 'gcp'")
+    query: str = Field(description="Trino SQL query to execute on rebilling data")
+
+
+def register_rebilling_tools(mcp):
+    """Register rebilling tools."""
+
+    @mcp.tool(
+        "get_rebilling_schema",
+        "Get the current schema (table name, columns, types, descriptions) for rebilling table. "
+        "Call this first to know the table name and available columns before querying.",
+        GetSchemaInput,
+    )
+    async def get_rebilling_schema(args: GetSchemaInput) -> str:
+        client = get_client()
+        schema = await client.get(f"/mcp/{args.provider}-rebilling/schema")
+
+        # Format schema for LLM
+        result = f"Schema for {args.provider}-rebilling:\n\n"
+        result += f"Table name: {schema['table']['name']}\n\n"
+        result += "Columns:\n"
+        for col in schema["columns"]:
+            result += f"  - {col['name']} ({col['type']})\n"
+
+        result += "\nDescriptions:\n"
+        for meta in schema["meta"]:
+            result += f"  - {meta['name']}: {meta['description']}\n"
+
+        if "sample" in schema and schema["sample"]:
+            result += "\nSample data (first row):\n"
+            sample = schema["sample"][0]
+            for key, value in sample.items():
+                result += f"  - {key}: {value}\n"
+
+        return result
+
+    @mcp.tool(
+        "query_rebilling",
+        "Execute a Trino SQL query on rebilling data. "
+        "Use get_rebilling_schema first to see available columns.",
+        QueryRebillingInput,
+    )
+    async def query_rebilling(args: QueryRebillingInput) -> str:
+        client = get_client()
+        result = await client.post(
+            f"/mcp/{args.provider}-rebilling/query", {"query": args.query}
+        )
+
+        # Format result
+        return str(result)