ghostserver 0.1.0__tar.gz

ghostserver-0.1.0/.gitignore

@@ -0,0 +1,10 @@
+__pycache__/
+*.pyc
+*.egg-info/
+dist/
+build/
+.pytest_cache/
+.venv/
+*.egg
+ghostserver.toml
+.ghostserver/

ghostserver-0.1.0/CLAUDE.md

@@ -0,0 +1,46 @@
+# Ghostserver — Local MCP Server
+
+Self-hosted MCP server connecting Claude Code to GitHub, Gmail, Google Calendar, Cloudflare, and AWS. All tokens stored locally via 1Password. No cloud proxy.
+
+## Quick Start
+
+```bash
+pip install -e ".[dev]"
+# One-time: set up Google OAuth
+python -m ghostserver.google_auth
+# Run server
+python -m ghostserver
+```
+
+## Architecture
+
+- **spine** manages frozen config registry + token store singleton
+- **gate** enforces per-service: enabled check, token validity, time-windowed rate limits
+- **fastmcp** handles MCP protocol; each adapter is a mounted sub-server
+- **1Password CLI** (`op`) stores all tokens — nothing in env vars or .env files
+
+## Config
+
+Edit `ghostserver.toml` to enable/disable services and set 1Password token references.
+
+## Tests
+
+```bash
+pytest -v
+```
+
+## 21 Tools
+
+**GitHub** (5): list_repos, create_issue, list_prs, get_pr, search_code
+**Gmail** (4): search, read, send, labels
+**Google Calendar** (4): list_events, create_event, free_busy, get_event
+**Cloudflare** (4): list_zones, list_dns, create_dns, list_workers
+**AWS** (4): list_buckets, list_objects, describe_instances, cloudwatch_metrics
+
+## Adding a new adapter
+
+1. Create `src/ghostserver/adapters/{name}.py`
+2. Define `SERVICE = "{name}"` and `server = FastMCP("{Name}")`
+3. Add `@server.tool` functions that call `check_gate(SERVICE)` first
+4. Add the service to `Config` in `config.py`
+5. Add to the import list in `adapters/__init__.py`

ghostserver-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Adam Thomas / GhostLogic LLC
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

ghostserver-0.1.0/PKG-INFO

@@ -0,0 +1,207 @@
+Metadata-Version: 2.4
+Name: ghostserver
+Version: 0.1.0
+Summary: Self-hosted MCP server connecting AI tools to GitHub, Gmail, Google Calendar, Cloudflare, and AWS
+Project-URL: Homepage, https://github.com/adam-scott-thomas/ghostserver
+Project-URL: Repository, https://github.com/adam-scott-thomas/ghostserver
+Project-URL: Issues, https://github.com/adam-scott-thomas/ghostserver/issues
+Author-email: Adam Thomas <adam@ghostlogic.dev>
+License-Expression: MIT
+License-File: LICENSE
+Keywords: ai,aws,cloudflare,github,gmail,mcp,model-context-protocol,tools
+Classifier: Development Status :: 3 - Alpha
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Software Development :: Libraries
+Requires-Python: >=3.12
+Requires-Dist: boto3>=1.35
+Requires-Dist: fastmcp>=2.0
+Requires-Dist: httpx>=0.27
+Requires-Dist: maelspine>=0.1.1
+Provides-Extra: dev
+Requires-Dist: pytest-asyncio>=0.24; extra == 'dev'
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Requires-Dist: respx>=0.22; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# GhostServer
+
+Self-hosted MCP server that connects any AI tool to your real accounts. Your tokens never leave your machine.
+
+Works with Claude Code, Cursor, VS Code Copilot, Windsurf, and any MCP-compatible client.
+
+## Why
+
+Every "MCP server" out there is either a setup wizard pointing at someone else's cloud, or locked to one AI vendor. GhostServer runs locally, stores credentials in your own vault, and speaks standard MCP protocol so any client can use it.
+
+## 21 Tools, 5 Services
+
+| Service | Tools |
+|---------|-------|
+| **GitHub** | list repos, create issues, list/get PRs, search code |
+| **Gmail** | search, read, send, list labels |
+| **Google Calendar** | list events, create events, free/busy, get event |
+| **Cloudflare** | list zones, DNS records, create DNS, list Workers |
+| **AWS** | S3 buckets/objects, EC2 instances, CloudWatch metrics |
+
+## Install
+
+```bash
+pip install ghostserver
+```
+
+Or from source:
+
+```bash
+git clone https://github.com/adam-scott-thomas/ghostserver.git
+cd ghostserver
+pip install -e ".[dev]"
+```
+
+## Quick Start
+
+### 1. Configure
+
+```bash
+cp ghostserver.toml.example ghostserver.toml
+```
+
+Edit `ghostserver.toml` — enable the services you want and set your credential references.
+
+### 2. Store Credentials
+
+GhostServer supports three credential backends:
+
+**Environment variables** (simplest):
+```toml
+[server]
+credential_backend = "env"
+
+[github]
+enabled = true
+token_ref = "GITHUB_TOKEN"
+```
+```bash
+export GITHUB_TOKEN="ghp_your_token_here"
+```
+
+**Credentials file** (no env pollution):
+```toml
+[server]
+credential_backend = "file"
+credential_file = "~/.ghostserver/credentials"
+
+[github]
+enabled = true
+token_ref = "GITHUB_TOKEN"
+```
+```
+# ~/.ghostserver/credentials
+GITHUB_TOKEN=ghp_your_token_here
+CLOUDFLARE_TOKEN=your_cf_token
+```
+
+**1Password CLI** (most secure):
+```toml
+[server]
+credential_backend = "op"
+
+[github]
+enabled = true
+token_ref = "op://Development/GitHub PAT/credential"
+```
+
+**Auto-detect** (default): tries 1Password, then credentials file, then env vars.
+
+### 3. Google Services (one-time setup)
+
+Gmail and Google Calendar require OAuth. Run the setup wizard once:
+
+```bash
+python -m ghostserver.google_auth
+```
+
+This opens your browser, gets consent, and stores the refresh token in your chosen backend.
+
+### 4. Connect to your AI tool
+
+**Claude Code:**
+```bash
+claude mcp add --transport stdio ghostserver -- python -m ghostserver
+```
+
+**Cursor / VS Code:**
+Add to your MCP settings:
+```json
+{
+  "ghostserver": {
+    "command": "python",
+    "args": ["-m", "ghostserver"]
+  }
+}
+```
+
+**Any MCP client (stdio):**
+```bash
+python -m ghostserver
+```
+
+## Architecture
+
+```
+Your AI Tool (Claude Code, Cursor, etc.)
+  |
+  | MCP protocol (stdio)
+  |
+  v
+GhostServer (local process)
+  |
+  |-- spine (frozen config registry)
+  |-- gate (per-service rate limiting + enabled checks)
+  |-- token store (pluggable: 1Password / env / file)
+  |
+  |-- GitHub adapter ──> api.github.com
+  |-- Gmail adapter ──> gmail.googleapis.com
+  |-- Calendar adapter ──> googleapis.com/calendar
+  |-- Cloudflare adapter ──> api.cloudflare.com
+  |-- AWS adapter ──> boto3 (local credentials)
+```
+
+Every adapter is a single file. The gate enforces rate limits per service. Spine provides the frozen config singleton so adapters don't pass objects around.
+
+## Adding Your Own Adapter
+
+Create `src/ghostserver/adapters/myservice.py`:
+
+```python
+from fastmcp import FastMCP
+from spine import Core
+from ghostserver.gate import check_gate
+
+SERVICE = "myservice"
+server = FastMCP("My Service")
+
+@server.tool
+async def myservice_do_thing(param: str) -> dict:
+    """Description for the AI client."""
+    check_gate(SERVICE)
+    tokens = Core.instance().get("tokens")
+    token = tokens.get(Core.instance().get("config").myservice.token_ref)
+    # ... call your API ...
+    return {"result": "done"}
+```
+
+Add the service config to `config.py`, add the module name to `adapters/__init__.py`, done. Submit a PR.
+
+## Development
+
+```bash
+git clone https://github.com/adam-scott-thomas/ghostserver.git
+cd ghostserver
+pip install -e ".[dev]"
+pytest -v
+```
+
+## License
+
+MIT

ghostserver-0.1.0/README.md

@@ -0,0 +1,181 @@
+# GhostServer
+
+Self-hosted MCP server that connects any AI tool to your real accounts. Your tokens never leave your machine.
+
+Works with Claude Code, Cursor, VS Code Copilot, Windsurf, and any MCP-compatible client.
+
+## Why
+
+Every "MCP server" out there is either a setup wizard pointing at someone else's cloud, or locked to one AI vendor. GhostServer runs locally, stores credentials in your own vault, and speaks standard MCP protocol so any client can use it.
+
+## 21 Tools, 5 Services
+
+| Service | Tools |
+|---------|-------|
+| **GitHub** | list repos, create issues, list/get PRs, search code |
+| **Gmail** | search, read, send, list labels |
+| **Google Calendar** | list events, create events, free/busy, get event |
+| **Cloudflare** | list zones, DNS records, create DNS, list Workers |
+| **AWS** | S3 buckets/objects, EC2 instances, CloudWatch metrics |
+
+## Install
+
+```bash
+pip install ghostserver
+```
+
+Or from source:
+
+```bash
+git clone https://github.com/adam-scott-thomas/ghostserver.git
+cd ghostserver
+pip install -e ".[dev]"
+```
+
+## Quick Start
+
+### 1. Configure
+
+```bash
+cp ghostserver.toml.example ghostserver.toml
+```
+
+Edit `ghostserver.toml` — enable the services you want and set your credential references.
+
+### 2. Store Credentials
+
+GhostServer supports three credential backends:
+
+**Environment variables** (simplest):
+```toml
+[server]
+credential_backend = "env"
+
+[github]
+enabled = true
+token_ref = "GITHUB_TOKEN"
+```
+```bash
+export GITHUB_TOKEN="ghp_your_token_here"
+```
+
+**Credentials file** (no env pollution):
+```toml
+[server]
+credential_backend = "file"
+credential_file = "~/.ghostserver/credentials"
+
+[github]
+enabled = true
+token_ref = "GITHUB_TOKEN"
+```
+```
+# ~/.ghostserver/credentials
+GITHUB_TOKEN=ghp_your_token_here
+CLOUDFLARE_TOKEN=your_cf_token
+```
+
+**1Password CLI** (most secure):
+```toml
+[server]
+credential_backend = "op"
+
+[github]
+enabled = true
+token_ref = "op://Development/GitHub PAT/credential"
+```
+
+**Auto-detect** (default): tries 1Password, then credentials file, then env vars.
+
+### 3. Google Services (one-time setup)
+
+Gmail and Google Calendar require OAuth. Run the setup wizard once:
+
+```bash
+python -m ghostserver.google_auth
+```
+
+This opens your browser, gets consent, and stores the refresh token in your chosen backend.
+
+### 4. Connect to your AI tool
+
+**Claude Code:**
+```bash
+claude mcp add --transport stdio ghostserver -- python -m ghostserver
+```
+
+**Cursor / VS Code:**
+Add to your MCP settings:
+```json
+{
+  "ghostserver": {
+    "command": "python",
+    "args": ["-m", "ghostserver"]
+  }
+}
+```
+
+**Any MCP client (stdio):**
+```bash
+python -m ghostserver
+```
+
+## Architecture
+
+```
+Your AI Tool (Claude Code, Cursor, etc.)
+  |
+  | MCP protocol (stdio)
+  |
+  v
+GhostServer (local process)
+  |
+  |-- spine (frozen config registry)
+  |-- gate (per-service rate limiting + enabled checks)
+  |-- token store (pluggable: 1Password / env / file)
+  |
+  |-- GitHub adapter ──> api.github.com
+  |-- Gmail adapter ──> gmail.googleapis.com
+  |-- Calendar adapter ──> googleapis.com/calendar
+  |-- Cloudflare adapter ──> api.cloudflare.com
+  |-- AWS adapter ──> boto3 (local credentials)
+```
+
+Every adapter is a single file. The gate enforces rate limits per service. Spine provides the frozen config singleton so adapters don't pass objects around.
+
+## Adding Your Own Adapter
+
+Create `src/ghostserver/adapters/myservice.py`:
+
+```python
+from fastmcp import FastMCP
+from spine import Core
+from ghostserver.gate import check_gate
+
+SERVICE = "myservice"
+server = FastMCP("My Service")
+
+@server.tool
+async def myservice_do_thing(param: str) -> dict:
+    """Description for the AI client."""
+    check_gate(SERVICE)
+    tokens = Core.instance().get("tokens")
+    token = tokens.get(Core.instance().get("config").myservice.token_ref)
+    # ... call your API ...
+    return {"result": "done"}
+```
+
+Add the service config to `config.py`, add the module name to `adapters/__init__.py`, done. Submit a PR.
+
+## Development
+
+```bash
+git clone https://github.com/adam-scott-thomas/ghostserver.git
+cd ghostserver
+pip install -e ".[dev]"
+pytest -v
+```
+
+## License
+
+MIT