@gently/mcp-server

@gently/mcp-server

MCP server for gently. Agents query the knowledge graph over stdio; authorization uses gently's device flow (approve in the console — no tokens in your MCP config).

Run

npx -y @gently/mcp-server

Auth

On the first tool call without credentials, the server returns a console URL and a short code. Approve there, then retry the same tool call so gently can finish signing in. Credentials stay on the machine (owner-only) and refresh automatically. A pending device code is kept across process restarts so a short-lived npx probe does not mint a new code after you already approved.

For CI, set GENTLY_TOKEN to a bearer token instead of using the device flow.

Configure

Point the server at your gently deployment:

Variable	Required	Purpose
GENTLY_API_URL	yes	Graph API base URL (include /v1)
GENTLY_IDENTITY_URL	yes	Identity base URL used for device auth
GENTLY_GRAPH	no	Graph id (defaults to the deployment default)
GENTLY_CLIENT_NAME	no	Label shown on the approval screen
GENTLY_TOKEN	no	Bearer token; skips device flow (CI)

Example MCP client entry:

{
  "mcpServers": {
    "gently": {
      "command": "npx",
      "args": ["-y", "@gently/mcp-server"],
      "env": {
        "GENTLY_API_URL": "<your-graph-api>/v1",
        "GENTLY_IDENTITY_URL": "<your-identity-url>"
      }
    }
  }
}

Project init

Writes gently agent guidance into the current repo:

npx -y -p @gently/mcp-server gently-mcp-init

SCIP sync (ADR-0024)

Enrich the graph with a simplified SCIP JSON index (not full protobuf). Uploads are per JWT sub: each developer keeps a separate head on the same branch. Requires graph:write (and graph:read for head checks).

When to sync — MCP boot auto-checks when GENTLY_SCIP_AUTO is unset/1 (set 0 to disable). Agents should prefer gently_scip_sync over force upload. Read tools (gently_query / gently_path / gently_impact) never upload.

Index path — GENTLY_SCIP_PATH or .gently/index.scip.json. Optional GENTLY_SCIP_CMD regenerates the index before upload when stale.

MCP tools

• gently_scip_sync — upload only if local content hash ≠ this identity's server head
• gently_upload_scip — force upload (path or inline index)

CLI:

# Change-detected (preferred)
npx -y -p @gently/mcp-server gently-mcp-scip-upload --sync --source github:org/repo

# Force upload
npx -y -p @gently/mcp-server gently-mcp-scip-upload \
  --file ./index.scip.json \
  --source github:org/repo

Bodies over 1 MiB are rejected by the edge.

License

MIT