Metadata-Version: 2.4
Name: gcontext-mcp
Version: 0.3.3
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: keyring>=25
Requires-Dist: mcp<2,>=1
Requires-Dist: python-dotenv>=1
Description-Content-Type: text/markdown

# gcontext

**The workspace your agent works in**: tasks it tracks, integrations it operates,
scripts it runs. Structure lives in the cloud so every session starts oriented;
**secret values and script execution never leave your machine**.

One prompt like *"ship the launch discount: new payment link in Stripe, point
promo.example.com at the site, update the launch task"* and your agent reads the
integration docs, runs the scripts locally with keys injected from your local
secret store, and checks off the task, without a single key entering the conversation.

## Get started (2 minutes)

```bash
uvx gcontext-mcp login   # browser sign-in at https://app.gcontext.ai mints a token
```

Then add it to Claude Code:

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

Free up to 30 files, no credit card. Needs `uv`/`uvx` on your PATH.

## What your agent gets

- **Tasks**: typed folders with goals, steps, and progress notes the agent
  maintains, so the next session picks up exactly where the last one stopped.
- **Integrations**: docs per third-party service (what it is, allowed/never
  operations, which secret NAMES it needs) that act as the agent's operations
  manual and guardrails.
- **Local script execution**: `tool_run_script` runs Python on YOUR machine with
  secret values injected from `~/.gcontext/.env` (chmod 0600; OS keychain opt-in
  via `GCONTEXT_SECRET_BACKEND=keychain`) and scrubbed from every output the agent sees.
- **A secret-name registry**: the cloud knows only NAMES and descriptions;
  values are filled once via a local browser form and stay on your machine.

## The privacy split

| Lives in the cloud | Never leaves your machine |
|---|---|
| Folder structure, docs, task state | Secret VALUES (`~/.gcontext/.env`, keychain opt-in) |
| Secret NAMES + present/missing flags | Script and shell execution |
| Activity metadata (names, token counts) | Script outputs before scrubbing |

Why: pasting API keys into a chat is how keys end up in logs and screenshots,
and a cloud that executes your code with your keys HAS your keys. gcontext
gives the agent full operational ability with zero key custody.

## Other clients and modes

**Claude Desktop** (no CLI): edit the config file (Settings → Developer → Edit
Config; macOS `~/Library/Application Support/Claude/claude_desktop_config.json`,
Windows `%APPDATA%\Claude\claude_desktop_config.json`), then fully restart:

```json
{
  "mcpServers": {
    "gcontext": {
      "command": "uvx",
      "args": ["gcontext-mcp"],
      "env": { "GCONTEXT_TOKEN": "<your token>" }
    }
  }
}
```

Keep the server name `gcontext` (or change it in the dashboard's Settings);
every prompt the dashboard copies references the server by that name. Desktop
has no slash-command prompts (`/use-integration`, etc.); you drive the same
tools by plain chat.

**Self-hosting**: same product, your server, one `docker compose up` and a
single token. See [SELF_HOSTING.md](./SELF_HOSTING.md) or
https://gcontext.ai/self-hosting.

**Pure-local dev** (no cloud, own SQLite), from a checkout:

```bash
claude mcp add gcontext -- 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_delete(path)` — `tool_write_file` auto-creates missing parent folders
- `tool_secrets(action="list"|"register"|"unregister", name, description)`,
  `tool_setup_secrets(form=True)`
- `tool_run_script(code)` - runs Python locally with secrets injected from the local store (`~/.gcontext/.env` by default)

## 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 secret environment from the local store regardless of what's registered.

1. `tool_secrets(action="register", name, description)` - declare a required secret.
2. `tool_setup_secrets()` - opens a local browser form where the user fills in the values; they are stored in `~/.gcontext/.env` (chmod 0600), or the OS keychain with `GCONTEXT_SECRET_BACKEND=keychain` (`form=False` appends blank `NAME=` lines to the `.env` instead).
3. `tool_secrets()` - shows `present` 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_secrets(action="register")`.
2. To act, read the file, generate Python, and call `tool_run_script`.
3. Secret values resolve from the local store (`~/.gcontext/.env` by default, keychain opt-in) at run time - never stored in the DB.

## Security / trust model

`tool_run_script` runs **arbitrary Python locally with your real secret values 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)

- `GCONTEXT_API_URL` - backend origin (default `https://app.gcontext.ai`; set for self-host).
- `GCONTEXT_TOKEN` - the dashboard-minted token.
- `MCP_MINIMAL_DB` - SQLite path for pure-local mode (default `db.sqlite` next to `server.py`).
- `MCP_MINIMAL_ENV_FILE` - secret-values file (default `~/.gcontext/.env`).
- `GCONTEXT_SECRET_BACKEND` - `env` (default: values in the 0600 `.env`) or `keychain` (OS keychain).

## Developing

Tests and the three-ring test architecture: see [tests/README.md](./tests/README.md).
Run everything with `make test`.
