agami-serve

name: agami-serve description: "Wires the local agami MCP server (mcp_server.py) into the Claude Desktop app in one step, so you can ask your database questions from Claude Desktop — not just inside Claude Code. Auto-detects the right Python interpreter (the one with your DB driver), copies the two self-contained server files to a stable /local/serve/ so the config survives plugin updates, and safely merges the entry into claude_desktop_config.json (backup + atomic write, preserving every other key). The local server is the mirror of the hosted Agami connector — same tools, local backend — so this is also how a developer feels the exact experience their business end-users would get." when_to_use: "Use when the user says 'set up agami for Claude Desktop', 'use agami in the Claude app', 'hook up the MCP server', 'let me test what my end users would see', '/agami-serve', or otherwise wants agami available outside Claude Code. Requires agami-connect to have run first (needs credentials + a semantic model). NOT needed to use agami inside Claude Code — the skills already work there."

agami serve — wire the local MCP server into Claude Desktop

You are setting up the local agami MCP server so the user can query their database from the Claude Desktop app (or any client that reads a claude_desktop_config.json-style file). This is the local mirror of the hosted "Ask Agami" connector: same tool surface (list_datasources, get_datasource_schema, get_prompt_examples, execute_sql, log_feedback), but backed by the user's local model + local execution. Everything stays on the machine; the server is stdio-only, has no auth, and makes no network call.

The heavy lifting is done by a deterministic helper — scripts/setup_desktop_mcp.py. This skill's job is to run it, read its output, and handle the two things that need a human: a missing DB driver, and the app restart.

Conversation style

• Tight. This is a one-shot setup tool, not a tutorial. Run the helper, report what it did, give the restart line.
• Honest about surfaces. Claude Desktop is the target here; if the user is already in Claude Code, remind them the skills already work there — the MCP server is for other clients.

Phase −1: Plan-mode preflight

Run the detection + ask logic from shared/plan-mode-check.md. This skill needs Bash (to run the helper, which writes files). If plan mode is active, refuse with: "I can't wire up Claude Desktop in plan mode — it writes files (the serve dir + your desktop config). Switch to Auto or Edit Automatically mode (Shift+Tab to cycle) and re-invoke me." DO NOT write a plan file. DO NOT call ExitPlanMode.

Phase 0: Preflight

1. Credentials present — <artifacts_dir>/local/credentials must exist for the active profile. If missing, invoke /agami-connect first; the server needs a connection to execute against.
2. Model present — <artifacts_dir>/<profile>/org.yaml must exist (so the server has a semantic model to serve). If not, invoke /agami-connect.
3. Profile — default to the active profile. If $ARGUMENTS names a profile, pass it through as --profile <name>.

Phase 1: Run the setup helper

Show the plan first with --dry-run, then do it for real:

# 1. Preview (writes nothing)
python3 "$AGAMI_PLUGIN_ROOT/scripts/setup_desktop_mcp.py" --dry-run

# 2. Apply
python3 "$AGAMI_PLUGIN_ROOT/scripts/setup_desktop_mcp.py"

Pass --profile <name> if the user named one. (For a developer iterating on the server from a checkout, --in-place points the config at the checkout instead of copying to <artifacts_dir>/local/serve — mention this only if they ask.)

Phase 2: Handle the two human cases

• Driver missing (exit code 3). The helper couldn't find a Python that can import the DB driver. Relay its suggested pip install ... line, offer to run it, then re-run the helper. Example: python3 -m pip install psycopg2-binary.
• Wrote successfully. Tell the user, in one or two lines:
  1. Fully quit the Claude Desktop app (Cmd+Q on macOS — not just close the window), then reopen it.
  2. In Claude Desktop, ask "What datasources does agami see?" — it should call list_datasources and return their profiles.
  3. If it doesn't appear, the log is at ~/Library/Logs/Claude/mcp-server-agami.log.

Phase 3: Orient them (one short paragraph)

Close with: this is the same toolset their business end-users would use through the hosted Agami connector — the only difference is the backend (their local files vs a shared, governed, always-on cloud). So what they just felt in Claude Desktop is the end-user experience. If they want it for a team (one shared model, evals, governance, reachable from web/mobile/Cowork), that's the hosted product — see docs/open-vs-hosted.md in the repo (https://github.com/AgamiAI/LiteBi/blob/main/docs/open-vs-hosted.md).

Notes

• The setup is idempotent — re-running updates the agami entry in place and re-copies the server files. Re-run after a plugin update to refresh the copy.
• It never clobbers other config: every other key and MCP server is preserved, and the previous config is backed up to a timestamped .bak-<epoch> file.
• It does not touch credentials and adds no network surface (see docs/privacy.md in the repo).