ide

package
v0.2.0-rc.2 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Jul 4, 2026 License: MIT Imports: 10 Imported by: 0

Documentation

Overview

Package ide provides detection and configuration for IDE/agent MCP integrations.

The package centers on three interfaces:

  • Adapter: identity + detection (every supported tool implements this).
  • Writer: Adapter + the methods needed to merge an MCP entry into a config file. Tools whose MCP setup we automate.
  • Hinter: Adapter + a one-shot Hint() string. Tools we detect but can't auto-configure (e.g. Claude Desktop where remote MCP requires OAuth via Settings -> Connectors). The CLI prints the hint instead.

Adding a new tool means dropping a file in this package, implementing either Writer or Hinter, and appending to Registry.

Index

Constants

View Source 
const MCPServerName = "dbgorilla"

MCPServerName is the key under which dbgorilla registers its MCP server in any tool's config. Kept stable across adapters so users see the same name in every IDE.

Variables

View Source 
var ErrJSONCRefused = fmt.Errorf(
	"target config file appears to be JSONC (has // comments); refusing to " +
		"write -- run with --print-config to get the entry to paste manually",
)

ErrJSONCRefused is returned when the target config file has a .jsonc extension or contains // comments. We refuse to write rather than silently destroy the user's comments. Caller should print the entry and instruct the user to paste manually.

View Source 
var Registry = []Adapter{
	&ClaudeCode{},
	&ClaudeDesktop{},
	&Cursor{},
	&VSCode{},
	&Opencode{},
	&Gemini{},
}

Registry holds every supported tool. Order is preserved -- shows up in help text and detection output the same way.

Functions

func SupportedSlugs 

func SupportedSlugs() []string

SupportedSlugs returns all known slugs (writers and hinters), in Registry order, for help text.

Types

type Adapter 

type Adapter interface {
	// Name is the human-readable tool name (e.g. "Claude Code").
	Name() string
	// Slug is the CLI flag value (e.g. "claude-code").
	Slug() string
	// Detect returns true when the tool appears installed.
	Detect() bool
}

Adapter is the minimal interface every supported tool implements.

func DetectInstalled 

func DetectInstalled() []Adapter

DetectInstalled returns adapters whose tool is present on the system.

func Find 

func Find(slug string) Adapter

Find returns the adapter matching the given slug, or nil.

type ClaudeCode 

type ClaudeCode struct{}

ClaudeCode is the Anthropic CLI agent. The preferred MCP-setup path is shelling to `claude mcp add` (handles managed-org allowlist policies); this adapter exists for the direct-write fallback when the `claude` CLI isn't on PATH.

func (*ClaudeCode) BuildEntry 

func (c *ClaudeCode) BuildEntry(mcpURL, apiKey string) map[string]any

func (*ClaudeCode) ConfigPath 

func (c *ClaudeCode) ConfigPath(scope Scope) (string, error)

ConfigPath returns the per-scope MCP config path:

  • User: ~/.claude.json (or %APPDATA%\Claude\claude.json on Windows). This is Claude Code's combined settings file -- merge logic in WriteMCPConfig preserves every other top-level key.
  • Project: .mcp.json in the current working directory. MCP-only file intended to be checked into source control.

func (*ClaudeCode) DefaultScope 

func (c *ClaudeCode) DefaultScope() Scope

func (*ClaudeCode) Detect 

func (c *ClaudeCode) Detect() bool

func (*ClaudeCode) Name 

func (c *ClaudeCode) Name() string

func (*ClaudeCode) Slug 

func (c *ClaudeCode) Slug() string

func (*ClaudeCode) SupportedScopes 

func (c *ClaudeCode) SupportedScopes() []Scope

func (*ClaudeCode) TopLevelKey 

func (c *ClaudeCode) TopLevelKey() string

type ClaudeDesktop 

type ClaudeDesktop struct{}

ClaudeDesktop is the Anthropic desktop app. It supports remote HTTP MCP only via Settings -> Connectors (UI flow, OAuth-based). The claude_desktop_config.json file ignores HTTP entries silently. Implement only Hinter, never Writer.

func (*ClaudeDesktop) Detect 

func (c *ClaudeDesktop) Detect() bool

func (*ClaudeDesktop) Hint 

func (c *ClaudeDesktop) Hint(mcpURL string) string

Hint returns the manual setup instructions. Claude Desktop's HTTP MCP requires Settings -> Connectors and a paid plan; there's no config file path that accepts a Bearer token.

func (*ClaudeDesktop) Name 

func (c *ClaudeDesktop) Name() string

func (*ClaudeDesktop) Slug 

func (c *ClaudeDesktop) Slug() string

type Cursor 

type Cursor struct{}

Cursor is the AI-first VS Code fork. Its MCP config is a dedicated JSON file (mcp.json), not part of the larger Cursor settings.

func (*Cursor) BuildEntry 

func (c *Cursor) BuildEntry(mcpURL, apiKey string) map[string]any

func (*Cursor) ConfigPath 

func (c *Cursor) ConfigPath(scope Scope) (string, error)

ConfigPath:

  • User: ~/.cursor/mcp.json
  • Project: .cursor/mcp.json (in the current working directory)

func (*Cursor) DefaultScope 

func (c *Cursor) DefaultScope() Scope

func (*Cursor) Detect 

func (c *Cursor) Detect() bool

func (*Cursor) Name 

func (c *Cursor) Name() string

func (*Cursor) Slug 

func (c *Cursor) Slug() string

func (*Cursor) SupportedScopes 

func (c *Cursor) SupportedScopes() []Scope

func (*Cursor) TopLevelKey 

func (c *Cursor) TopLevelKey() string

type Gemini 

type Gemini struct{}

Gemini is Google's gemini-cli. MCP config lives in settings.json under "mcpServers". For Streamable HTTP transport the entry uses "httpUrl" (not "url" -- that selects the deprecated SSE transport).

func (*Gemini) BuildEntry 

func (g *Gemini) BuildEntry(mcpURL, apiKey string) map[string]any

func (*Gemini) ConfigPath 

func (g *Gemini) ConfigPath(scope Scope) (string, error)

ConfigPath:

  • User: ~/.gemini/settings.json
  • Project: .gemini/settings.json in cwd

func (*Gemini) DefaultScope 

func (g *Gemini) DefaultScope() Scope

func (*Gemini) Detect 

func (g *Gemini) Detect() bool

func (*Gemini) Name 

func (g *Gemini) Name() string

func (*Gemini) Slug 

func (g *Gemini) Slug() string

func (*Gemini) SupportedScopes 

func (g *Gemini) SupportedScopes() []Scope

func (*Gemini) TopLevelKey 

func (g *Gemini) TopLevelKey() string

type Hinter 

type Hinter interface {
	Adapter
	Hint(mcpURL string) string
}

Hinter is implemented by tools we detect but can't auto-configure. Hint() returns a multi-line string with manual setup instructions.

type Opencode 

type Opencode struct{}

Opencode is sst/opencode -- TUI agent. MCP config lives inside the shared opencode.json under the "mcp" key; entries take type:"remote" for HTTP servers.

func (*Opencode) BuildEntry 

func (o *Opencode) BuildEntry(mcpURL, apiKey string) map[string]any

func (*Opencode) ConfigPath 

func (o *Opencode) ConfigPath(scope Scope) (string, error)

ConfigPath:

  • User: ~/.config/opencode/opencode.json
  • Project: opencode.json in cwd

Note: opencode also accepts opencode.jsonc with comments. We deliberately target the .json variant for writes and let the JSONC-refusal logic in WriteMCPConfig redirect users to --print-config if they're using JSONC.

func (*Opencode) DefaultScope 

func (o *Opencode) DefaultScope() Scope

func (*Opencode) Detect 

func (o *Opencode) Detect() bool

func (*Opencode) Name 

func (o *Opencode) Name() string

func (*Opencode) Slug 

func (o *Opencode) Slug() string

func (*Opencode) SupportedScopes 

func (o *Opencode) SupportedScopes() []Scope

func (*Opencode) TopLevelKey 

func (o *Opencode) TopLevelKey() string

type Scope 

type Scope string

Scope describes which config layer to write. 

const (
	ScopeUser    Scope = "user"
	ScopeProject Scope = "project"
)

type VSCode 

type VSCode struct{}

VSCode targets the official MCP support shipped in mid-2025. Its config file uses the top-level key "servers" -- NOT "mcpServers". This is the most common copy-paste mistake when wiring up MCP across IDEs.

func (*VSCode) BuildEntry 

func (v *VSCode) BuildEntry(mcpURL, apiKey string) map[string]any

func (*VSCode) ConfigPath 

func (v *VSCode) ConfigPath(scope Scope) (string, error)

ConfigPath:

  • Project: .vscode/mcp.json (in cwd)
  • User: OS-specific Code/User/mcp.json

func (*VSCode) DefaultScope 

func (v *VSCode) DefaultScope() Scope

DefaultScope: project. VS Code's MCP UX is built around .vscode/mcp.json living next to the workspace -- that's the conventional place. Users who want global setup pass --scope user explicitly.

func (*VSCode) Detect 

func (v *VSCode) Detect() bool

func (*VSCode) Name 

func (v *VSCode) Name() string

func (*VSCode) Slug 

func (v *VSCode) Slug() string

func (*VSCode) SupportedScopes 

func (v *VSCode) SupportedScopes() []Scope

func (*VSCode) TopLevelKey 

func (v *VSCode) TopLevelKey() string

TopLevelKey is "servers", not "mcpServers". This is the load-bearing difference between VS Code and every other IDE in this package.

type WriteResult 

type WriteResult struct {
	Path       string
	BackupPath string // empty if no backup needed (fresh file or no-op)
	Created    bool   // true if the config file did not exist before
	Updated    bool   // true if an existing dbgorilla entry was replaced
	NoOp       bool   // true if the existing entry already matched
}

WriteResult describes what WriteMCPConfig did. Useful for the caller to print accurate user-facing messages ("wrote", "updated", "no change").

func WriteMCPConfig 

func WriteMCPConfig(w Writer, mcpURL, apiKey string, scope Scope) (WriteResult, error)

WriteMCPConfig merges the dbgorilla MCP entry into the tool's config file at the requested scope. Safety contract:

  • Always reads existing config first; never starts from a blank slate.
  • Backs up to <path>.backup.<timestamp> (mode 0600) before any write.
  • Preserves every other top-level key in the file.
  • Preserves every other entry under the MCP top-level key.
  • Refuses to write JSONC files (would destroy comments) -- caller should fall back to --print-config.
  • Idempotent: no write when the existing entry already matches.

Returns the result struct for accurate user messaging.

type Writer 

type Writer interface {
	Adapter
	// SupportedScopes returns which scopes this tool's config supports.
	// Most tools support {ScopeUser, ScopeProject}; some only support one.
	SupportedScopes() []Scope
	// DefaultScope returns the scope to use when the user passes no flag.
	DefaultScope() Scope
	// ConfigPath returns the absolute path to the MCP config file for the
	// requested scope. Project-scoped paths are resolved against the
	// current working directory.
	ConfigPath(scope Scope) (string, error)
	// TopLevelKey is the JSON key under which MCP servers live in this
	// tool's config (e.g. "mcpServers" for Claude/Cursor/Gemini, "servers"
	// for VS Code, "mcp" for opencode).
	TopLevelKey() string
	// BuildEntry returns the per-tool MCP server entry shape for the
	// dbgorilla server. Different tools have different field names
	// (e.g. Gemini wants "httpUrl", others want "url").
	BuildEntry(mcpURL, apiKey string) map[string]any
}

Writer is implemented by tools whose MCP config we can write.

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.