gcontext-mcp 0.1.1__py3-none-any.whl

gcontext_mcp-0.1.1.dist-info/METADATA

@@ -0,0 +1,71 @@
+Metadata-Version: 2.4
+Name: gcontext-mcp
+Version: 0.1.1
+Summary: gcontext connector — local MCP bridge: cloud structure, local secret values
+Project-URL: Homepage, https://gcontext.ai
+License-Expression: MIT
+Requires-Python: >=3.11
+Requires-Dist: mcp<2,>=1
+Description-Content-Type: text/markdown
+
+# mcp-minimal
+
+A single local Python MCP server: a files/folders tree + a secret-name registry in
+SQLite, plus on-the-fly Python script execution with the local `.env` injected.
+Secret VALUES never leave this machine and never enter the database.
+
+## Setup
+
+```bash
+cd apps/mcp-minimal
+cp .env.example .env   # fill in your secret values
+```
+
+## Add to Claude Code
+
+```bash
+claude mcp add mcp-minimal -- uv run --directory /ABS/PATH/TO/apps/mcp-minimal python server.py
+```
+
+## Tools
+
+- `tool_list_dir(path="/")`, `tool_read_file(path)`, `tool_write_file(path, content)`,
+  `tool_create_folder(path)`, `tool_delete(path)`
+- `tool_list_secrets()`, `tool_register_secret(name, description)`, `tool_unregister_secret(name)`,
+  `tool_scaffold_env()`
+- `tool_run_script(code)` - runs `uv run --env-file .env python -c "<code>"`
+
+## The secret registry
+
+The registry holds secret NAMES + descriptions only — it is for **setup and
+verification**, not runtime. It does NOT gate `tool_run_script`, which injects the
+whole `.env` regardless of what's registered.
+
+1. `tool_register_secret(name, description)` - declare a required secret.
+2. `tool_scaffold_env()` - append blank `NAME=` lines to `.env` for any registered
+   secret not yet present, so the user just fills in the values.
+3. `tool_list_secrets()` - shows `present_locally` per name so you can confirm setup.
+
+## How it works
+
+1. Write a file describing a 3rd-party operation and which secret NAMES it needs;
+   declare those names with `tool_register_secret`.
+2. To act, read the file, generate Python, and call `tool_run_script`.
+3. Secret values resolve from the local `.env` at run time - never stored in the DB.
+
+## Security / trust model
+
+`tool_run_script` runs **arbitrary Python locally with your real `.env` injected** —
+there is no sandbox. It is exactly as trusted as whatever drives the server. Run it
+on your own machine only; never expose this server remotely.
+
+## Script contract
+
+- Read secrets via `os.environ["VAR"]` - never hardcode, never `load_dotenv`.
+- Use only registered names that show `present_locally: true`.
+- Exit codes: `0` OK, `2` missing secret (`KeyError`), `1` any other failure.
+
+## Config (env vars)
+
+- `MCP_MINIMAL_DB` - SQLite path (default `db.sqlite` next to `server.py`).
+- `MCP_MINIMAL_ENV_FILE` - secret-values file (default `.env` next to `server.py`).

gcontext_mcp-0.1.1.dist-info/RECORD

@@ -0,0 +1,5 @@
+server.py,sha256=nFRLxA_pMK4TIAZda4wfBwezfvWby8d0APANQ0Qdtzk,19833
+gcontext_mcp-0.1.1.dist-info/METADATA,sha256=h8fJyzf3neGpPzgNtOsyLDEGUKjEd01YXzCFoEuHB-E,2655
+gcontext_mcp-0.1.1.dist-info/WHEEL,sha256=mffPy8wBnZQn2VnJUU5jE99KsxaSfiyMHV9Yt0aLVxs,87
+gcontext_mcp-0.1.1.dist-info/entry_points.txt,sha256=MbwKdNapqvlXulgeFjIW-B_v1gaOX2HGClkIwqX4u_w,68
+gcontext_mcp-0.1.1.dist-info/RECORD,,

gcontext_mcp-0.1.1.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.30.1
+Root-Is-Purelib: true
+Tag: py3-none-any

gcontext_mcp-0.1.1.dist-info/entry_points.txt

@@ -0,0 +1,3 @@
+[console_scripts]
+gcontext = server:main
+gcontext-mcp = server:main

server.py

@@ -0,0 +1,493 @@
+import os, sqlite3, subprocess, datetime
+
+APP_DIR = os.path.dirname(os.path.abspath(__file__))
+
+# Local home for this machine's data. Secret VALUES never leave here.
+GCONTEXT_HOME = os.path.expanduser("~/.gcontext")
+# Baked default cloud endpoint for the packaged connector; override with GCONTEXT_API_URL.
+DEFAULT_API_URL = "https://api.gcontext.ai"
+
+def _db_path():
+    return os.environ.get("MCP_MINIMAL_DB", os.path.join(GCONTEXT_HOME, "db.sqlite"))
+
+def _env_file():
+    return os.environ.get("MCP_MINIMAL_ENV_FILE", os.path.join(GCONTEXT_HOME, ".env"))
+
+# --- cloud mode -------------------------------------------------------------
+# When GCONTEXT_API_URL is set, structure (files/folders/secret NAMES) is read
+# from and written to the cloud over a single /rpc endpoint. Secret VALUES and
+# run_script ALWAYS stay local. Unset = pure local SQLite (the default).
+import json as _json, urllib.request as _urlreq
+
+def _cloud():
+    url = os.environ.get("GCONTEXT_API_URL")
+    return (url.rstrip("/"), os.environ.get("GCONTEXT_TOKEN", "")) if url else None
+
+def _rpc(fn, **args):
+    base, token = _cloud()
+    req = _urlreq.Request(
+        base + "/rpc",
+        data=_json.dumps({"fn": fn, "args": args}).encode(),
+        method="POST",
+        headers={"Authorization": "Bearer " + token, "Content-Type": "application/json"},
+    )
+    with _urlreq.urlopen(req, timeout=30) as r:
+        d = _json.loads(r.read() or b"null")
+    if isinstance(d, dict) and "error" in d:
+        raise ValueError(d["error"])
+    return d["result"]
+
+def secret_names():
+    """[{name, description, present_locally}] from the registry — cloud or local.
+    In cloud mode present_locally is the value the connector last reported (see
+    report_presence); the cloud never sees secret VALUES, only this boolean."""
+    if _cloud():
+        return _rpc("secret_names")
+    rows = db().execute("select name,description,present_locally from secrets order by name").fetchall()
+    return [{"name": n, "description": d, "present_locally": bool(p)} for (n, d, p) in rows]
+
+def report_presence(present):
+    """Record which secret NAMES have a value in the local .env. Stores booleans only —
+    never values. Called by the connector; proxied to the cloud when in cloud mode."""
+    if _cloud():
+        return _rpc("report_presence", present=present)
+    conn = db()
+    conn.execute("update secrets set present_locally=0")
+    for name in present:
+        conn.execute("update secrets set present_locally=1 where name=?", (name,))
+    conn.commit()
+    return {"ok": True, "present": present}
+
+def push_presence():
+    """Connector → cloud: report which registered secret names are set in the local .env.
+    Fire-and-forget: swallows errors so a cloud hiccup never breaks a tool call."""
+    if not _cloud():
+        return
+    try:
+        local = env_keys()
+        report_presence([s["name"] for s in secret_names() if s["name"] in local])
+    except Exception:
+        pass
+
+def all_files():
+    """All file paths — cloud when configured, else local."""
+    if _cloud():
+        return _rpc("all_files")
+    return [p for (p,) in db().execute("select path from nodes where type='file' order by path")]
+
+def stamp():
+    return datetime.datetime.now(datetime.timezone.utc).isoformat()
+
+def norm(p):
+    parts = [x for x in p.split("/") if x]
+    return "/" + "/".join(parts)
+
+def parent(path):
+    parts = [x for x in path.split("/") if x]
+    return "/" + "/".join(parts[:-1])
+
+def db():
+    conn = sqlite3.connect(_db_path())
+    conn.execute(
+        "create table if not exists nodes("
+        "path text primary key,"
+        "type text not null check(type in ('file','folder')),"
+        "content text not null default '',"
+        "updated_at text not null)"
+    )
+    conn.execute(
+        "create table if not exists secrets("
+        "name text primary key,"
+        "description text not null default '',"
+        "present_locally integer not null default 0)"  # presence reported by the connector
+    )
+    try:  # migrate older dbs that lack the column
+        conn.execute("alter table secrets add column present_locally integer not null default 0")
+    except sqlite3.OperationalError:
+        pass
+    return conn
+
+def ensure_parents(conn, path, now):
+    parts = [x for x in path.split("/") if x]
+    for i in range(1, len(parts)):
+        anc = "/" + "/".join(parts[:i])
+        row = conn.execute("select type from nodes where path=?", (anc,)).fetchone()
+        if row is None:
+            conn.execute(
+                "insert into nodes(path,type,content,updated_at) values(?,?,?,?)",
+                (anc, "folder", "", now),
+            )
+        elif row[0] == "file":
+            raise ValueError(f"path is a file, cannot contain children: {anc}")
+
+def list_dir(path="/"):
+    if _cloud():
+        return _rpc("list_dir", path=path)
+    path = norm(path)
+    conn = db()
+    if path != "/":
+        row = conn.execute("select type from nodes where path=?", (path,)).fetchone()
+        if row is None:
+            raise ValueError(f"no such folder: {path}")
+        if row[0] != "folder":
+            raise ValueError(f"path is a file: {path}")
+    rows = conn.execute("select path,type from nodes").fetchall()
+    return [{"path": p, "type": t} for (p, t) in rows if parent(p) == path]
+
+def read_file(path):
+    if _cloud():
+        return _rpc("read_file", path=path)
+    path = norm(path)
+    row = db().execute("select type,content from nodes where path=?", (path,)).fetchone()
+    if row is None:
+        raise ValueError(f"no such file: {path}")
+    if row[0] != "file":
+        raise ValueError(f"path is a folder: {path}")
+    return {"path": path, "content": row[1]}
+
+def write_file(path, content):
+    if _cloud():
+        return _rpc("write_file", path=path, content=content)
+    path = norm(path)
+    if path == "/":
+        raise ValueError("cannot write to root")
+    now = stamp()
+    conn = db()
+    existing = conn.execute("select type from nodes where path=?", (path,)).fetchone()
+    if existing and existing[0] == "folder":
+        raise ValueError(f"path is a folder: {path}")
+    ensure_parents(conn, path, now)
+    conn.execute(
+        "insert into nodes(path,type,content,updated_at) values(?,?,?,?) "
+        "on conflict(path) do update set content=excluded.content, updated_at=excluded.updated_at",
+        (path, "file", content, now),
+    )
+    conn.commit()
+    return {"path": path, "ok": True}
+
+def create_folder(path):
+    if _cloud():
+        return _rpc("create_folder", path=path)
+    path = norm(path)
+    if path == "/":
+        return {"path": "/", "ok": True}
+    now = stamp()
+    conn = db()
+    existing = conn.execute("select type from nodes where path=?", (path,)).fetchone()
+    if existing:
+        if existing[0] == "file":
+            raise ValueError(f"path is a file: {path}")
+        return {"path": path, "ok": True}
+    ensure_parents(conn, path, now)
+    conn.execute(
+        "insert into nodes(path,type,content,updated_at) values(?,?,?,?)",
+        (path, "folder", "", now),
+    )
+    conn.commit()
+    return {"path": path, "ok": True}
+
+def delete(path):
+    if _cloud():
+        return _rpc("delete", path=path)
+    path = norm(path)
+    if path == "/":
+        raise ValueError("cannot delete root")
+    conn = db()
+    row = conn.execute("select type from nodes where path=?", (path,)).fetchone()
+    if row is None:
+        raise ValueError(f"no such path: {path}")
+    if row[0] == "folder":
+        conn.execute("delete from nodes where path=? or path like ?", (path, path + "/%"))
+    else:
+        conn.execute("delete from nodes where path=?", (path,))
+    conn.commit()
+    return {"path": path, "deleted": True}
+
+def env_keys():
+    # Parse .env the way `uv run --env-file` does, so present_locally never lies
+    # about what run_script will actually see. ponytail: handles `export ` and
+    # quoted keys; ceiling = no multiline/backslash-continued values (rare). Swap
+    # in python-dotenv only if that ever bites.
+    keys = set()
+    path = _env_file()
+    if os.path.exists(path):
+        with open(path) as f:
+            for line in f:
+                line = line.strip()
+                if not line or line.startswith("#") or "=" not in line:
+                    continue
+                key = line.split("=", 1)[0].strip()
+                if key.startswith("export "):
+                    key = key[len("export "):].strip()
+                key = key.strip("'\"")
+                if key:
+                    keys.add(key)
+    return keys
+
+def list_secrets():
+    # Cloud mode: presence is what the connector reported to the cloud (so a HOSTED
+    # dashboard, which can't see the local .env, still shows readiness).
+    # Local mode: compute presence directly from the local .env.
+    if _cloud():
+        return secret_names()  # already carries present_locally from the cloud
+    local = env_keys()
+    return [
+        {"name": s["name"], "description": s["description"], "present_locally": s["name"] in local}
+        for s in secret_names()
+    ]
+
+def register_secret(name, description=""):
+    if _cloud():
+        return _rpc("register_secret", name=name, description=description)
+    conn = db()
+    conn.execute(
+        "insert into secrets(name,description) values(?,?) "
+        "on conflict(name) do update set description=excluded.description",
+        (name, description),
+    )
+    conn.commit()
+    return {"name": name, "ok": True}
+
+def unregister_secret(name):
+    if _cloud():
+        return _rpc("unregister_secret", name=name)
+    conn = db()
+    conn.execute("delete from secrets where name=?", (name,))
+    conn.commit()
+    return {"name": name, "removed": True}
+
+def scaffold_env():
+    """Append placeholder `NAME=` lines to .env for every registered secret not
+    already present. Never writes values, never reads existing values. Idempotent."""
+    rows = secret_names()  # cloud or local
+    present = env_keys()
+    missing = [(s["name"], s["description"]) for s in rows if s["name"] not in present]
+    if missing:
+        path = _env_file()
+        os.makedirs(os.path.dirname(path), exist_ok=True)
+        head = "" if (os.path.exists(path) and os.path.getsize(path)) else \
+            "# Secret VALUES live here, on the client only. Fill in the blanks.\n"
+        with open(path, "a") as f:
+            if head:
+                f.write(head)
+            for name, desc in missing:
+                if desc:
+                    f.write(f"# {desc}\n")
+                f.write(f"{name}=\n")
+    return {"added": [n for (n, _) in missing], "already_present": sorted(present)}
+
+def overview():
+    """Live snapshot: counts of integrations, folders, files, secrets, plus a path tree."""
+    if _cloud():
+        return _rpc("overview")
+    conn = db()
+    rows = conn.execute("select path,type from nodes order by path").fetchall()
+    files = [p for p, t in rows if t == "file"]
+    folders = [p for p, t in rows if t == "folder"]
+    integrations = [p for p in folders if parent(p) == "/integrations"]
+    secrets = conn.execute("select count(*) from secrets").fetchone()[0]
+    tree = "\n".join(
+        ("  " * (p.count("/") - 1)) + p.rsplit("/", 1)[-1] + ("/" if t == "folder" else "")
+        for p, t in rows
+    )
+    return {
+        "integrations": len(integrations),
+        "integration_names": [p.rsplit("/", 1)[-1] for p in integrations],
+        "folders": len(folders),
+        "files": len(files),
+        "secrets": secrets,
+        "tree": tree or "(empty)",
+    }
+
+def run_script(code):
+    """Run Python locally with the local .env injected via `uv run --env-file`.
+    Scripts read secrets from os.environ. Returns exit_code/stdout/stderr."""
+    cmd = ["uv", "run"]
+    # ponytail: skip --env-file when there's no .env, else uv errors on the missing
+    # file instead of running the script. Means run_script works with zero secrets too.
+    if os.path.exists(_env_file()):
+        cmd += ["--env-file", _env_file()]
+    cmd += ["python", "-c", code]
+    try:
+        proc = subprocess.run(
+            cmd,
+            cwd=APP_DIR,
+            capture_output=True,
+            text=True,
+            timeout=300,
+        )
+        return {"exit_code": proc.returncode, "stdout": proc.stdout, "stderr": proc.stderr}
+    except subprocess.TimeoutExpired as e:
+        return {"exit_code": 124, "stdout": e.stdout or "", "stderr": "timeout after 300s"}
+
+
+from mcp.server.fastmcp import FastMCP, Context
+
+def build_instructions():
+    """On-connect intro built from the current workspace. Static for the session —
+    live state comes from tool_overview + resources/list_changed."""
+    try:
+        o = overview()
+    except Exception:
+        # cloud unreachable at boot — don't block startup; tools still work once it's up.
+        return ("This is your gcontext workspace (cloud structure + local secret values). "
+                "Call tool_overview to see what's available.")
+    names = ", ".join(o["integration_names"]) or "none yet"
+    return (
+        "This is your gcontext workspace: a virtual filesystem of context docs plus a "
+        "registry of secret NAMES (values stay in the local .env, never here).\n"
+        f"Right now: {o['integrations']} integration(s) ({names}), "
+        f"{o['files']} file(s), {o['secrets']} secret name(s).\n"
+        "To see everything live, call the tool_overview tool. "
+        "To start working with an integration, use the /use-integration prompt. "
+        "To load a specific file into context, @-mention its mcpfs:// resource."
+    )
+
+# Static placeholder at import time (no DB/network side effects). The real, workspace-
+# aware instructions are set in main() once cloud defaults are applied.
+server = FastMCP("gcontext", instructions=(
+    "Your gcontext workspace: cloud structure + local secret values. "
+    "Call tool_overview to see what's available, or use the /use-integration prompt."))
+
+@server.tool()
+def tool_list_dir(path: str = "/") -> list:
+    """List the direct children (files and folders) of a folder path."""
+    return list_dir(path)
+
+@server.tool()
+def tool_read_file(path: str) -> dict:
+    """Read a file's text content by path."""
+    return read_file(path)
+
+@server.tool()
+async def tool_write_file(path: str, content: str, ctx: Context) -> dict:
+    """Create or overwrite a file; missing parent folders are auto-created."""
+    r = write_file(path, content)
+    await ctx.session.send_resource_list_changed()
+    return r
+
+@server.tool()
+async def tool_create_folder(path: str, ctx: Context) -> dict:
+    """Create an (optionally empty) folder; missing parents are auto-created."""
+    r = create_folder(path)
+    await ctx.session.send_resource_list_changed()
+    return r
+
+@server.tool()
+async def tool_delete(path: str, ctx: Context) -> dict:
+    """Delete a file, or a folder and all its descendants (recursive)."""
+    r = delete(path)
+    await ctx.session.send_resource_list_changed()
+    return r
+
+@server.tool()
+def tool_list_secrets() -> list:
+    """List registered secret NAMES with descriptions and whether each is present in the local .env. Values are never stored or returned."""
+    return list_secrets()
+
+@server.tool()
+def tool_register_secret(name: str, description: str = "") -> dict:
+    """Declare a required secret NAME (no value). The registry is for setup & verification only — it does NOT affect run_script, which injects the whole .env regardless."""
+    r = register_secret(name, description)
+    push_presence()  # re-evaluate the new name against the local .env
+    return r
+
+@server.tool()
+def tool_refresh_secrets() -> list:
+    """Re-check the local .env and report which secrets are set (booleans only) to the cloud, then return the updated list. Use after editing your .env so the dashboard badges update without reconnecting."""
+    push_presence()
+    return list_secrets()
+
+@server.tool()
+def tool_unregister_secret(name: str) -> dict:
+    """Remove a secret name from the registry. Does not touch the local .env."""
+    return unregister_secret(name)
+
+@server.tool()
+def tool_check_secrets() -> dict:
+    """Verify each registered secret has a value in the local .env. Returns {all_set, secrets:[{name, present}]}. Honest even when the dashboard is cloud-hosted, since this runs locally. Values are never read or returned."""
+    secrets = [{"name": r["name"], "present": r["present_locally"]} for r in list_secrets()]
+    return {"all_set": all(s["present"] for s in secrets), "secrets": secrets}
+
+@server.tool()
+def tool_scaffold_env() -> dict:
+    """Append placeholder `NAME=` lines to the local .env for every registered secret not yet present, so the user just fills in the blanks. Never writes or reads values."""
+    r = scaffold_env()
+    push_presence()  # reflect the (still-empty) names so the cloud knows what's pending
+    return r
+
+@server.tool()
+def tool_run_script(code: str) -> dict:
+    """Run arbitrary Python LOCALLY with the whole local .env injected. Read secrets via os.environ['NAME']. Trusted-caller only — never expose this server remotely. Returns exit_code/stdout/stderr."""
+    return run_script(code)
+
+@server.tool()
+def tool_overview() -> dict:
+    """Live snapshot of everything available: counts of integrations, folders, files, and secrets, plus a path tree. Call this first to orient."""
+    return overview()
+
+# --- Resources: expose every file so the user can @-mention it to load context ---
+# Dynamic handlers on the low-level server read the DB on each request, so the
+# resource list always reflects current state (FastMCP's resource registry is static).
+import mcp.types as _t
+
+_SCHEME = "mcpfs"
+
+def _to_uri(path):
+    return f"{_SCHEME}://{path}"  # path starts with "/" -> mcpfs:///integrations/...
+
+def _from_uri(uri):
+    return norm(str(uri).split("://", 1)[1])
+
+@server._mcp_server.list_resources()
+async def _list_resources():
+    return [
+        _t.Resource(
+            uri=_to_uri(p),
+            name=p,
+            description=f"file at {p}",
+            mimeType="text/markdown" if p.endswith(".md") else "text/plain",
+        )
+        for p in all_files()
+    ]
+
+@server._mcp_server.read_resource()
+async def _read_resource(uri):
+    return read_file(_from_uri(uri))["content"]
+
+@server.prompt()
+def use_integration(name: str) -> str:
+    """Load an integration's doc + registered secret names to start working with it."""
+    doc = read_file(f"/integrations/{name}/info.md")["content"]
+    secs = ", ".join(s["name"] for s in list_secrets()) or "(none registered)"
+    return (
+        f"You are about to work with the '{name}' integration.\n\n"
+        f"--- /integrations/{name}/info.md ---\n{doc}\n\n"
+        f"Registered secret names: {secs}\n"
+        "Use the run_script tool to perform the requested operation; secrets are "
+        "available via os.environ['NAME']."
+    )
+
+@server.prompt()
+def check_secrets() -> str:
+    """Check whether every registered secret is set in the local .env."""
+    return (
+        "Call the tool_check_secrets tool. Report one line per secret as "
+        "`NAME ✓` if present or `NAME ✗` if missing. If any are missing, suggest "
+        "running tool_scaffold_env to stub them into the local .env."
+    )
+
+def main():
+    # Packaged entry point (`uvx gcontext`). Default to the hosted cloud for structure;
+    # secret VALUES stay in the local .env. Set GCONTEXT_API_URL to override (e.g. dev).
+    os.environ.setdefault("GCONTEXT_API_URL", DEFAULT_API_URL)
+    os.makedirs(os.path.dirname(_env_file()), exist_ok=True)
+    try:
+        push_presence()  # tell the cloud which secrets are set locally (booleans only)
+    except Exception:
+        pass  # cloud unreachable at boot — non-fatal
+    server._mcp_server.instructions = build_instructions()  # now reflects live state
+    server.run()
+
+if __name__ == "__main__":
+    main()