ghostserver 0.1.0__py3-none-any.whl

ghostserver/__init__.py

@@ -0,0 +1,2 @@
+"""Ghostserver — Local MCP server connecting AI tools to real services."""
+__version__ = "0.1.0"

ghostserver/__main__.py

@@ -0,0 +1,4 @@
+"""Allow running as: python -m ghostserver"""
+from ghostserver.server import main
+
+main()

ghostserver/adapters/__init__.py

@@ -0,0 +1,22 @@
+"""Service adapters. Each module exposes a `server` FastMCP instance and a `SERVICE` name."""
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from types import ModuleType
+
+
+def discover() -> list[tuple[str, "ModuleType"]]:
+    """Return (service_name, module) for each adapter that defines SERVICE and server."""
+    import importlib
+
+    adapters = []
+    for name in ["github", "gmail", "gcal", "cloudflare", "aws"]:
+        try:
+            mod = importlib.import_module(f"ghostserver.adapters.{name}")
+            if hasattr(mod, "server") and hasattr(mod, "SERVICE"):
+                adapters.append((mod.SERVICE, mod))
+        except ImportError:
+            pass
+    return adapters

ghostserver/adapters/aws.py

@@ -0,0 +1,111 @@
+"""AWS adapter — 4 tools for S3, EC2, and CloudWatch."""
+from __future__ import annotations
+
+from typing import Annotated
+
+import boto3
+from fastmcp import FastMCP
+from pydantic import Field
+from spine import Core
+
+from ghostserver.gate import check_gate
+
+SERVICE = "aws"
+
+server = FastMCP("AWS")
+
+
+def _region() -> str:
+    return Core.instance().get("config").aws.region
+
+
+@server.tool
+async def aws_list_buckets() -> list[dict]:
+    """List all S3 buckets in the AWS account."""
+    check_gate(SERVICE)
+    s3 = boto3.client("s3", region_name=_region())
+    response = s3.list_buckets()
+    return [
+        {
+            "name": b["Name"],
+            "created": b["CreationDate"].isoformat() if hasattr(b["CreationDate"], "isoformat") else str(b["CreationDate"]),
+        }
+        for b in response.get("Buckets", [])
+    ]
+
+
+@server.tool
+async def aws_list_objects(
+    bucket: Annotated[str, Field(description="S3 bucket name")],
+    prefix: Annotated[str, Field(description="Key prefix to filter objects")] = "",
+    max_keys: Annotated[int, Field(description="Maximum number of objects to return", ge=1, le=1000)] = 20,
+) -> dict:
+    """List objects in an S3 bucket, optionally filtered by prefix."""
+    check_gate(SERVICE)
+    s3 = boto3.client("s3", region_name=_region())
+    response = s3.list_objects_v2(Bucket=bucket, Prefix=prefix, MaxKeys=max_keys)
+    objects = [
+        {
+            "key": obj["Key"],
+            "size": obj["Size"],
+            "modified": obj["LastModified"].isoformat() if hasattr(obj["LastModified"], "isoformat") else str(obj["LastModified"]),
+        }
+        for obj in response.get("Contents", [])
+    ]
+    return {
+        "count": len(objects),
+        "objects": objects,
+    }
+
+
+@server.tool
+async def aws_describe_instances(
+    instance_ids: Annotated[list[str], Field(description="List of EC2 instance IDs to describe; empty list returns all instances")] = [],
+) -> list[dict]:
+    """Describe EC2 instances, returning id, name, type, state, and IPs."""
+    check_gate(SERVICE)
+    ec2 = boto3.client("ec2", region_name=_region())
+    kwargs = {}
+    if instance_ids:
+        kwargs["InstanceIds"] = instance_ids
+    response = ec2.describe_instances(**kwargs)
+
+    instances = []
+    for reservation in response.get("Reservations", []):
+        for inst in reservation.get("Instances", []):
+            name = ""
+            for tag in inst.get("Tags", []):
+                if tag.get("Key") == "Name":
+                    name = tag.get("Value", "")
+                    break
+            instances.append({
+                "id": inst.get("InstanceId", ""),
+                "name": name,
+                "type": inst.get("InstanceType", ""),
+                "state": inst.get("State", {}).get("Name", ""),
+                "public_ip": inst.get("PublicIpAddress", ""),
+                "private_ip": inst.get("PrivateIpAddress", ""),
+            })
+    return instances
+
+
+@server.tool
+async def aws_cloudwatch_metrics(
+    namespace: Annotated[str, Field(description="CloudWatch namespace to list metrics for (e.g. 'AWS/EC2', 'AWS/S3')")],
+) -> list[dict]:
+    """List CloudWatch metrics for a given namespace, deduplicated by namespace+name."""
+    check_gate(SERVICE)
+    cw = boto3.client("cloudwatch", region_name=_region())
+    response = cw.list_metrics(Namespace=namespace)
+
+    seen: set[tuple[str, str]] = set()
+    metrics = []
+    for m in response.get("Metrics", []):
+        key = (m.get("Namespace", ""), m.get("MetricName", ""))
+        if key not in seen:
+            seen.add(key)
+            metrics.append({
+                "namespace": key[0],
+                "name": key[1],
+            })
+    return metrics

ghostserver/adapters/cloudflare.py

@@ -0,0 +1,121 @@
+"""Cloudflare adapter — 4 tools for zones, DNS, and Workers."""
+from __future__ import annotations
+
+from typing import Annotated
+from pydantic import Field
+
+import httpx
+from fastmcp import FastMCP
+from spine import Core
+from ghostserver.gate import check_gate
+
+SERVICE = "cloudflare"
+API = "https://api.cloudflare.com/client/v4"
+
+server = FastMCP("Cloudflare")
+
+
+def _headers() -> dict[str, str]:
+    tokens = Core.instance().get("tokens")
+    config = Core.instance().get("config")
+    token = tokens.get(config.cloudflare.token_ref)
+    return {
+        "Authorization": f"Bearer {token}",
+        "Content-Type": "application/json",
+    }
+
+
+@server.tool
+async def cf_list_zones() -> list[dict]:
+    """List all Cloudflare zones (domains) on the account."""
+    check_gate(SERVICE)
+    async with httpx.AsyncClient() as client:
+        resp = await client.get(
+            f"{API}/zones",
+            headers=_headers(),
+            params={"per_page": 50},
+        )
+        resp.raise_for_status()
+    data = resp.json()
+    return [
+        {"id": z["id"], "name": z["name"], "status": z["status"]}
+        for z in data["result"]
+    ]
+
+
+@server.tool
+async def cf_list_dns(
+    zone_id: Annotated[str, Field(description="Cloudflare zone ID")],
+    record_type: Annotated[str, Field(description="Optional DNS record type filter (e.g. A, CNAME, MX)")] = "",
+) -> list[dict]:
+    """List DNS records for a Cloudflare zone, with optional type filter."""
+    check_gate(SERVICE)
+    params: dict = {}
+    if record_type:
+        params["type"] = record_type
+    async with httpx.AsyncClient() as client:
+        resp = await client.get(
+            f"{API}/zones/{zone_id}/dns_records",
+            headers=_headers(),
+            params=params,
+        )
+        resp.raise_for_status()
+    data = resp.json()
+    return [
+        {
+            "id": r["id"],
+            "type": r["type"],
+            "name": r["name"],
+            "content": r["content"],
+            "ttl": r["ttl"],
+        }
+        for r in data["result"]
+    ]
+
+
+@server.tool
+async def cf_create_dns(
+    zone_id: Annotated[str, Field(description="Cloudflare zone ID")],
+    record_type: Annotated[str, Field(description="DNS record type (e.g. A, CNAME, TXT)")],
+    name: Annotated[str, Field(description="DNS record name (e.g. subdomain or @)")],
+    content: Annotated[str, Field(description="DNS record content (e.g. IP address or target hostname)")],
+    ttl: Annotated[int, Field(description="Time to live in seconds; 1 = automatic")] = 1,
+    proxied: Annotated[bool, Field(description="Whether to proxy traffic through Cloudflare")] = False,
+) -> dict:
+    """Create a new DNS record in a Cloudflare zone."""
+    check_gate(SERVICE)
+    payload = {
+        "type": record_type,
+        "name": name,
+        "content": content,
+        "ttl": ttl,
+        "proxied": proxied,
+    }
+    async with httpx.AsyncClient() as client:
+        resp = await client.post(
+            f"{API}/zones/{zone_id}/dns_records",
+            headers=_headers(),
+            json=payload,
+        )
+        resp.raise_for_status()
+    r = resp.json()["result"]
+    return {"id": r["id"], "type": r["type"], "name": r["name"], "content": r["content"]}
+
+
+@server.tool
+async def cf_list_workers(
+    account_id: Annotated[str, Field(description="Cloudflare account ID")],
+) -> list[dict]:
+    """List all Cloudflare Workers scripts for an account."""
+    check_gate(SERVICE)
+    async with httpx.AsyncClient() as client:
+        resp = await client.get(
+            f"{API}/accounts/{account_id}/workers/scripts",
+            headers=_headers(),
+        )
+        resp.raise_for_status()
+    data = resp.json()
+    return [
+        {"id": w["id"], "modified": w.get("modified_on", "")}
+        for w in data["result"]
+    ]

ghostserver/adapters/gcal.py

@@ -0,0 +1,178 @@
+"""Google Calendar adapter — 4 tools for listing, creating, and querying events."""
+from __future__ import annotations
+
+from datetime import datetime, timedelta, timezone
+from typing import Annotated
+
+import httpx
+from fastmcp import FastMCP
+from pydantic import Field
+from spine import Core
+
+from ghostserver.gate import check_gate
+
+SERVICE = "google"
+API = "https://www.googleapis.com/calendar/v3"
+
+server = FastMCP("Google Calendar")
+
+
+def _get_access_token() -> str:
+    core = Core.instance()
+    config = core.get("config")
+    tokens = core.get("tokens")
+
+    client_id = tokens.get(config.google.client_id_ref)
+    client_secret = tokens.get(config.google.client_secret_ref)
+    refresh_token = tokens.get(config.google.refresh_token_ref)
+
+    return tokens.refresh_google(
+        client_id=client_id,
+        client_secret=client_secret,
+        refresh_token=refresh_token,
+    )
+
+
+def _auth_headers() -> dict[str, str]:
+    return {"Authorization": f"Bearer {_get_access_token()}"}
+
+
+@server.tool
+async def gcal_list_events(
+    days_ahead: Annotated[int, Field(description="Number of days ahead to fetch events", ge=1, le=90)] = 7,
+    calendar_id: Annotated[str, Field(description="Calendar ID to query (default: primary)")] = "primary",
+) -> list[dict]:
+    """List upcoming calendar events within the specified number of days."""
+    check_gate(SERVICE)
+    headers = _auth_headers()
+
+    now = datetime.now(timezone.utc)
+    time_max = now + timedelta(days=days_ahead)
+
+    async with httpx.AsyncClient() as client:
+        resp = await client.get(
+            f"{API}/calendars/{calendar_id}/events",
+            headers=headers,
+            params={
+                "timeMin": now.isoformat(),
+                "timeMax": time_max.isoformat(),
+                "singleEvents": "true",
+                "orderBy": "startTime",
+            },
+        )
+        resp.raise_for_status()
+
+    items = resp.json().get("items", [])
+    results = []
+    for item in items:
+        start = item.get("start", {})
+        end = item.get("end", {})
+        results.append({
+            "id": item.get("id", ""),
+            "summary": item.get("summary", ""),
+            "start": start.get("dateTime", start.get("date", "")),
+            "end": end.get("dateTime", end.get("date", "")),
+            "url": item.get("htmlLink", ""),
+        })
+    return results
+
+
+@server.tool
+async def gcal_create_event(
+    summary: Annotated[str, Field(description="Event title/summary")],
+    start_time: Annotated[str, Field(description="Start datetime in ISO 8601 format (e.g. 2024-06-01T10:00:00Z)")],
+    end_time: Annotated[str, Field(description="End datetime in ISO 8601 format (e.g. 2024-06-01T11:00:00Z)")],
+    description: Annotated[str, Field(description="Optional event description")] = "",
+    calendar_id: Annotated[str, Field(description="Calendar ID to create the event in (default: primary)")] = "primary",
+) -> dict:
+    """Create a new calendar event."""
+    check_gate(SERVICE)
+    headers = {**_auth_headers(), "Content-Type": "application/json"}
+
+    body: dict = {
+        "summary": summary,
+        "start": {"dateTime": start_time, "timeZone": "UTC"},
+        "end": {"dateTime": end_time, "timeZone": "UTC"},
+    }
+    if description:
+        body["description"] = description
+
+    async with httpx.AsyncClient() as client:
+        resp = await client.post(
+            f"{API}/calendars/{calendar_id}/events",
+            headers=headers,
+            json=body,
+        )
+        resp.raise_for_status()
+
+    data = resp.json()
+    return {
+        "id": data.get("id", ""),
+        "summary": data.get("summary", ""),
+        "url": data.get("htmlLink", ""),
+    }
+
+
+@server.tool
+async def gcal_free_busy(
+    days_ahead: Annotated[int, Field(description="Number of days ahead to check for busy slots", ge=1, le=30)] = 3,
+) -> dict:
+    """Query free/busy information for the primary calendar."""
+    check_gate(SERVICE)
+    headers = {**_auth_headers(), "Content-Type": "application/json"}
+
+    now = datetime.now(timezone.utc)
+    time_max = now + timedelta(days=days_ahead)
+
+    async with httpx.AsyncClient() as client:
+        resp = await client.post(
+            f"{API}/freeBusy",
+            headers=headers,
+            json={
+                "timeMin": now.isoformat(),
+                "timeMax": time_max.isoformat(),
+                "items": [{"id": "primary"}],
+            },
+        )
+        resp.raise_for_status()
+
+    data = resp.json()
+    busy_slots = data.get("calendars", {}).get("primary", {}).get("busy", [])
+    return {
+        "busy_slots": busy_slots,
+        "count": len(busy_slots),
+    }
+
+
+@server.tool
+async def gcal_get_event(
+    event_id: Annotated[str, Field(description="Google Calendar event ID")],
+    calendar_id: Annotated[str, Field(description="Calendar ID containing the event (default: primary)")] = "primary",
+) -> dict:
+    """Fetch full details for a specific calendar event."""
+    check_gate(SERVICE)
+    headers = _auth_headers()
+
+    async with httpx.AsyncClient() as client:
+        resp = await client.get(
+            f"{API}/calendars/{calendar_id}/events/{event_id}",
+            headers=headers,
+        )
+        resp.raise_for_status()
+
+    data = resp.json()
+    start = data.get("start", {})
+    end = data.get("end", {})
+    attendees = [
+        {"email": a.get("email", ""), "status": a.get("responseStatus", "")}
+        for a in data.get("attendees", [])
+    ]
+    return {
+        "id": data.get("id", ""),
+        "summary": data.get("summary", ""),
+        "description": data.get("description", ""),
+        "start": start.get("dateTime", start.get("date", "")),
+        "end": end.get("dateTime", end.get("date", "")),
+        "attendees": attendees,
+        "url": data.get("htmlLink", ""),
+    }

ghostserver/adapters/github.py

@@ -0,0 +1,142 @@
+"""GitHub adapter — 5 tools for repos, issues, PRs, and code search."""
+from __future__ import annotations
+
+from typing import Annotated
+from pydantic import Field
+
+import httpx
+from fastmcp import FastMCP
+from spine import Core
+from ghostserver.gate import check_gate
+
+SERVICE = "github"
+API = "https://api.github.com"
+
+server = FastMCP("GitHub")
+
+
+def _headers() -> dict[str, str]:
+    tokens = Core.instance().get("tokens")
+    config = Core.instance().get("config")
+    token = tokens.get(config.github.token_ref)
+    return {
+        "Authorization": f"Bearer {token}",
+        "Accept": "application/vnd.github+json",
+        "X-GitHub-Api-Version": "2022-11-28",
+    }
+
+
+@server.tool
+async def github_list_repos(
+    sort: Annotated[str, Field(description="Sort by: updated, created, pushed, full_name")] = "updated",
+    per_page: Annotated[int, Field(description="Results per page (max 100)", ge=1, le=100)] = 30,
+) -> list[dict]:
+    """List your GitHub repositories, sorted by most recently updated."""
+    check_gate(SERVICE)
+    async with httpx.AsyncClient() as client:
+        resp = await client.get(
+            f"{API}/user/repos",
+            headers=_headers(),
+            params={"sort": sort, "per_page": per_page, "type": "owner"},
+        )
+        resp.raise_for_status()
+    return [
+        {"name": r["full_name"], "description": r["description"],
+         "url": r["html_url"], "stars": r["stargazers_count"], "language": r["language"]}
+        for r in resp.json()
+    ]
+
+
+@server.tool
+async def github_create_issue(
+    owner: Annotated[str, Field(description="Repository owner")],
+    repo: Annotated[str, Field(description="Repository name")],
+    title: Annotated[str, Field(description="Issue title")],
+    body: Annotated[str, Field(description="Issue body (markdown)")] = "",
+    labels: Annotated[list[str], Field(description="Labels to apply")] = [],
+) -> dict:
+    """Create a new issue in a GitHub repository."""
+    check_gate(SERVICE)
+    payload = {"title": title, "body": body}
+    if labels:
+        payload["labels"] = labels
+    async with httpx.AsyncClient() as client:
+        resp = await client.post(
+            f"{API}/repos/{owner}/{repo}/issues",
+            headers=_headers(),
+            json=payload,
+        )
+        resp.raise_for_status()
+    data = resp.json()
+    return {"number": data["number"], "title": data["title"], "url": data["html_url"]}
+
+
+@server.tool
+async def github_list_prs(
+    owner: Annotated[str, Field(description="Repository owner")],
+    repo: Annotated[str, Field(description="Repository name")],
+    state: Annotated[str, Field(description="Filter: open, closed, all")] = "open",
+) -> list[dict]:
+    """List pull requests for a GitHub repository."""
+    check_gate(SERVICE)
+    async with httpx.AsyncClient() as client:
+        resp = await client.get(
+            f"{API}/repos/{owner}/{repo}/pulls",
+            headers=_headers(),
+            params={"state": state, "per_page": 30},
+        )
+        resp.raise_for_status()
+    return [
+        {"number": p["number"], "title": p["title"], "state": p["state"],
+         "author": p["user"]["login"], "url": p["html_url"]}
+        for p in resp.json()
+    ]
+
+
+@server.tool
+async def github_get_pr(
+    owner: Annotated[str, Field(description="Repository owner")],
+    repo: Annotated[str, Field(description="Repository name")],
+    number: Annotated[int, Field(description="PR number")],
+) -> dict:
+    """Get details of a specific pull request."""
+    check_gate(SERVICE)
+    async with httpx.AsyncClient() as client:
+        resp = await client.get(
+            f"{API}/repos/{owner}/{repo}/pulls/{number}",
+            headers=_headers(),
+        )
+        resp.raise_for_status()
+    pr = resp.json()
+    return {
+        "number": pr["number"], "title": pr["title"], "state": pr["state"],
+        "body": pr.get("body", ""), "author": pr["user"]["login"],
+        "merged": pr["merged"], "additions": pr["additions"],
+        "deletions": pr["deletions"], "changed_files": pr["changed_files"],
+        "url": pr["html_url"],
+    }
+
+
+@server.tool
+async def github_search_code(
+    query: Annotated[str, Field(description="Search query (GitHub code search syntax)")],
+    per_page: Annotated[int, Field(description="Results per page", ge=1, le=100)] = 10,
+) -> dict:
+    """Search code across GitHub repositories."""
+    check_gate(SERVICE)
+    async with httpx.AsyncClient() as client:
+        resp = await client.get(
+            f"{API}/search/code",
+            headers=_headers(),
+            params={"q": query, "per_page": per_page},
+        )
+        resp.raise_for_status()
+    data = resp.json()
+    return {
+        "total_count": data["total_count"],
+        "items": [
+            {"file": i["name"], "path": i["path"],
+             "repo": i["repository"]["full_name"], "url": i["html_url"]}
+            for i in data["items"]
+        ],
+    }