Metadata-Version: 2.4
Name: gcontext-mcp
Version: 0.1.2
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

Published connector (talks to the hosted cloud at `https://api.gcontext.ai`):

```bash
claude mcp add-json gcontext '{"type":"stdio","command":"uvx","args":["gcontext-mcp"],"env":{"GCONTEXT_TOKEN":"<your token>"}}'
```

Get a token with `curl -X POST https://api.gcontext.ai/signup -d '{"email":"...","password":"..."}'`.
Pure-local (no cloud, own SQLite):

```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`).
