Add a gel configure-agent tool

[anbuzin]

We really want whoever uses Gel with LLMs to use our prompts and the MCP server because they make the experience a lot less frustrating. The setup process for different LLM code tools is very confusing, so Yury has proposed to add a dedicated CLI command to do just that.

Stuff to be configured

1. The MCP server: repo

{
  "mcpServers": {
      "gel": {
          "command": "uvx",
          "args": [
              "--refresh",
              "--directory",
              ".",
              "--from",
              "git+https://github.com/geldata/gel-mcp.git@refine-rules",
              "gel-mcp"
          ]
      }
  }
}

Anatomy of the command:

• refresh to avoid uv using the cached old version of the tools.
• --directory . to execute from current project's directory (lets Gel connect and run execute_query tool).
• --from <url> because we don't actually publish the Python package yet.

2. The Rules prompts (to instruct LLMs to use Gel correctly): general, python, typescript.

Editor configuration variants

Cursor has multiple options. Docs for MCP, prompts.

1. Project-wide: user stores MCP configuration in .cursor/mcp.json and prompt files in custom Markdown-ese in .cursor/rules/*.mdc.
   1. Note: need to manually toggle the server in the settings.
2. Global automatic: user clicks an Add to Cursor button in the readme, and that adds the MCP server to their editor globally.
3. Global prompt: user can manually add global rules using a clicky interface.

Zed limits programmatic ways to do things. Docs for MCP, prompts.

1. Project-wide: user stores the prompt in a .rules file at the root of the project. That file can contain links to other files using /file path/to/file.md syntax to create a nested document.
2. The MCP configuration can only be configured in the global settings.json using a semi-custom syntax.
3. Alternatively the prompt can be added globally and configured to auto-append via the Rules Library, which is a clicky interface. The MCP can be distributed via an extension, which Gel currently does not have (requires Treesitter grammar).

Claude Code offers a third way: Docs for MCP, prompts.

1. User or the agent creates a CLAUDE.md file to store prompts. That file can contain links to other files. Similar to a README.md, there can be multiple of this file located in nested directories, which the agent is going to treat as "scoped" to the enclosing directory.
2. User puts .mcp.json file at the root to configure the MCP server with normal syntax. There's also a claude CLI command for that.

CLI command outline

• gel configure-agent
• gel configure-agent <editor>: add / update configuration for the editor of choice.
• gel configure-agent list: show supported editors and their current setup status

1. Check if configuration for Gel / other tools already exists.
2. Create backups of files to be edited.
3. Download Gel's configuration files and merge with existing.
   1. For Cursor: .cursor/mcp.json and .cursor/rules/gel-*.mdc.
   2. For Claude Code: CLAUDE.md and docs/gel-*.md.
   3. For Zed: .rules and docs/gel-*.md
4. Print instructions where it's impossible to configure things programmatically.
   1. For Cursor: toggle the server in the GUI.
   2. For Zed: copy-pasteable snippet to put in settings.json, instruction for how to create auto-appendable prompt in the GUI.

Optionally offer an interactive mode to force the user to read the friendly manual and guide them to correct configuration.

[anbuzin]

Update for Claude Code. This is how you whitelist the server and all its tools in .claude/settings.local.json:

{
  "enableAllProjectMcpServers": true,
  "enabledMcpjsonServers": [
    "gel"
  ],
  "permissions": {
    "allow": [
      "mcp__gel__list_examples",
      "mcp__gel__fetch_example",
      "mcp__gel__try_query",
      "mcp__gel__execute_query"
    ]
  }
}

Update for Zed. This is the configuration to be inserted in ~/.config/zed/settings.json:

{
  "context_servers": {
    "gel": {
      "source": "custom",
      "command": {
        "path": "uvx",
        "args": [
          "--refresh",
          "--directory",
          ".",
          "--from",
          "git+https://github.com/geldata/gel-mcp.git",
          "gel-mcp"
        ],
        "env": {}
      }
    }
  }
}

[scotttrinh]

I know we have a significant number of Jetbrains users as well (probably more than Zed users) so want to consider https://www.jetbrains.com/help/ai-assistant/configure-an-mcp-server.html as well.

[1st1]

@anbuzin so it seems that both claude and cursor can be fully configured with a per-project file? And zed needs us to mess with the global config?

@scotttrinh can you modify our fastapi starter template to have configs for claude/cursor out of the box?

[scotttrinh]

can you modify our fastapi starter template to have configs for claude/cursor out of the box?

Yep, easily done!

[anbuzin]

@1st1 yes, weirdly enough. I'd expect Zed to provide the best integration seeing how they co-authored the spec.