Documentation
¶
Overview ¶
Package configimport provides functionality to import MCP server configurations from external tools like Claude Desktop, Claude Code, Cursor IDE, Codex CLI, and Gemini CLI.
Index ¶
- Constants
- Variables
- func GetAvailableServerNames(content []byte, formatHint ConfigFormat) ([]string, error)
- func IsNoServers(err error) bool
- func MapToServerConfig(parsed *ParsedServer, now time.Time) (*config.ServerConfig, []string, []string)
- func Reclassify(imported *ImportedServer)
- func SanitizeServerName(name string) (string, bool)
- func SuggestNameFromCommand(parts []string) string
- func SuggestNameFromURL(u *url.URL) string
- func ValidServerName(name string) error
- type ClaudeCodeConfig
- type ClaudeCodeParser
- type ClaudeCodeServerConfig
- type ClaudeDesktopConfig
- type ClaudeDesktopParser
- type ClaudeDesktopServerConfig
- type CodexConfig
- type CodexParser
- type CodexServerConfig
- type CommandParser
- type ConfigFormat
- type CursorAuthConfig
- type CursorMCPConfig
- type CursorParser
- type CursorServerConfig
- type DetectionResult
- type FailedServer
- type GeminiConfig
- type GeminiMCPGlobal
- type GeminiOAuth
- type GeminiParser
- type GeminiServerConfig
- type ImportError
- type ImportOptions
- type ImportResult
- type ImportSource
- type ImportSummary
- type ImportedField
- type ImportedServer
- type ParsedServer
- type Parser
- type SkippedServer
- type URLParser
Constants ¶
const ErrTypeNoServers = "no_servers"
ErrTypeNoServers is the ImportError.Type a parser returns when a recognised client config holds no MCP servers (empty or absent server map).
const SkipReasonSelfReference = "self_reference"
SkipReasonSelfReference marks a source entry that points back at this mcpproxy instance (typically the entry Connect wrote into the client's config). Importing it would proxy mcpproxy through itself.
Variables ¶
var ErrUnknownFormat = fmt.Errorf("unable to detect configuration format: supported formats are Claude Desktop, Claude Code, Cursor IDE, Codex CLI, Gemini CLI, a pasted URL, or a pasted command line")
ErrUnknownFormat is returned when the configuration format cannot be detected.
Functions ¶
func GetAvailableServerNames ¶
func GetAvailableServerNames(content []byte, formatHint ConfigFormat) ([]string, error)
GetAvailableServerNames returns the list of server names found in the config. This is useful for listing available servers when the requested server is not found.
func IsNoServers ¶ added in v0.70.0
IsNoServers reports whether err is the "client config has no MCP servers" import error. A malformed file or an undetectable format is not.
func MapToServerConfig ¶
func MapToServerConfig(parsed *ParsedServer, now time.Time) (*config.ServerConfig, []string, []string)
MapToServerConfig converts a ParsedServer to MCPProxy's ServerConfig. Returns the mapped server config, list of skipped fields, and any warnings.
func Reclassify ¶ added in v0.70.0
func Reclassify(imported *ImportedServer)
Reclassify recomputes the FR-040 preview enrichment (EnvFields, HeaderFields, Summary, Tags) from the imported server's CURRENT Server.Env/Headers/etc. Callers that mutate the server after Import (e.g. applying credential overrides) use it so the enrichment describes the values actually persisted rather than the original source file's.
func SanitizeServerName ¶
SanitizeServerName attempts to create a valid server name from an invalid one. Returns the sanitized name and a boolean indicating if sanitization was needed.
func SuggestNameFromCommand ¶ added in v0.70.0
SuggestNameFromCommand derives a display name from a tokenized command line. For a package runner (npx/uvx/pipx) it prefers the package name over the runner binary, e.g. ["npx","-y","@modelcontextprotocol/server-filesystem"] -> "server-filesystem". Exported so the CLI and httpapi preview can reuse it verbatim.
func SuggestNameFromURL ¶ added in v0.70.0
SuggestNameFromURL derives a display name from a parsed URL's host, e.g. "https://api.githubcopilot.com/mcp/" -> "githubcopilot". Exported so the CLI and httpapi preview can reuse it verbatim.
func ValidServerName ¶
ValidServerName checks if a server name is valid for MCPProxy
Types ¶
type ClaudeCodeConfig ¶
type ClaudeCodeConfig struct {
MCPServers map[string]ClaudeCodeServerConfig `json:"mcpServers"`
}
ClaudeCodeConfig represents the Claude Code configuration file structure.
type ClaudeCodeParser ¶
type ClaudeCodeParser struct{}
ClaudeCodeParser parses Claude Code configuration files.
func (*ClaudeCodeParser) Format ¶
func (p *ClaudeCodeParser) Format() ConfigFormat
Format returns the configuration format this parser handles.
func (*ClaudeCodeParser) Parse ¶
func (p *ClaudeCodeParser) Parse(content []byte) ([]*ParsedServer, error)
Parse parses Claude Code configuration content.
type ClaudeCodeServerConfig ¶
type ClaudeCodeServerConfig struct {
Type string `json:"type,omitempty"` // stdio, http, sse, websocket
Command string `json:"command,omitempty"`
Args []string `json:"args,omitempty"`
Env map[string]string `json:"env,omitempty"`
URL string `json:"url,omitempty"`
Headers map[string]string `json:"headers,omitempty"`
}
ClaudeCodeServerConfig represents a single server in Claude Code config.
type ClaudeDesktopConfig ¶
type ClaudeDesktopConfig struct {
GlobalShortcut string `json:"globalShortcut,omitempty"`
MCPServers map[string]ClaudeDesktopServerConfig `json:"mcpServers"`
}
ClaudeDesktopConfig represents the Claude Desktop configuration file structure.
type ClaudeDesktopParser ¶
type ClaudeDesktopParser struct{}
ClaudeDesktopParser parses Claude Desktop configuration files.
func (*ClaudeDesktopParser) Format ¶
func (p *ClaudeDesktopParser) Format() ConfigFormat
Format returns the configuration format this parser handles.
func (*ClaudeDesktopParser) Parse ¶
func (p *ClaudeDesktopParser) Parse(content []byte) ([]*ParsedServer, error)
Parse parses Claude Desktop configuration content.
type ClaudeDesktopServerConfig ¶
type ClaudeDesktopServerConfig struct {
Command string `json:"command"`
Args []string `json:"args"`
Env map[string]string `json:"env,omitempty"`
}
ClaudeDesktopServerConfig represents a single server in Claude Desktop config.
type CodexConfig ¶
type CodexConfig struct {
MCPServers map[string]CodexServerConfig `toml:"mcp_servers"`
}
CodexConfig represents the Codex CLI configuration file structure (TOML).
type CodexParser ¶
type CodexParser struct{}
CodexParser parses Codex CLI configuration files (TOML).
func (*CodexParser) Format ¶
func (p *CodexParser) Format() ConfigFormat
Format returns the configuration format this parser handles.
func (*CodexParser) Parse ¶
func (p *CodexParser) Parse(content []byte) ([]*ParsedServer, error)
Parse parses Codex CLI configuration content.
type CodexServerConfig ¶
type CodexServerConfig struct {
// Stdio transport
Command string `toml:"command,omitempty"`
Args []string `toml:"args,omitempty"`
Cwd string `toml:"cwd,omitempty"`
Env map[string]string `toml:"env,omitempty"`
EnvVars []string `toml:"env_vars,omitempty"` // Forward from shell env
// HTTP transport
URL string `toml:"url,omitempty"`
BearerToken string `toml:"bearer_token,omitempty"`
BearerTokenEnvVar string `toml:"bearer_token_env_var,omitempty"`
HTTPHeaders map[string]string `toml:"http_headers,omitempty"`
EnvHTTPHeaders map[string]string `toml:"env_http_headers,omitempty"`
// Behavior
Enabled *bool `toml:"enabled,omitempty"`
EnabledTools []string `toml:"enabled_tools,omitempty"` // Not supported
DisabledTools []string `toml:"disabled_tools,omitempty"` // Not supported
// Timeouts (not supported)
StartupTimeoutSec float64 `toml:"startup_timeout_sec,omitempty"`
StartupTimeoutMs int64 `toml:"startup_timeout_ms,omitempty"`
ToolTimeoutSec float64 `toml:"tool_timeout_sec,omitempty"`
}
CodexServerConfig represents a single server in Codex config.
type CommandParser ¶ added in v0.70.0
type CommandParser struct{}
CommandParser parses a single pasted command line into one local/stdio server (Spec 109 FR-064), splitting it with the shared quote-aware tokenizer. Preview never executes anything — Parse only tokenizes text.
func (*CommandParser) Format ¶ added in v0.70.0
func (p *CommandParser) Format() ConfigFormat
Format implements Parser.
func (*CommandParser) Parse ¶ added in v0.70.0
func (p *CommandParser) Parse(content []byte) ([]*ParsedServer, error)
Parse implements Parser.
type ConfigFormat ¶
type ConfigFormat string
ConfigFormat represents supported configuration formats
const ( FormatUnknown ConfigFormat = "unknown" FormatClaudeDesktop ConfigFormat = "claude_desktop" FormatClaudeCode ConfigFormat = "claude_code" FormatCursor ConfigFormat = "cursor" FormatCodex ConfigFormat = "codex" FormatGemini ConfigFormat = "gemini" // FormatURL and FormatCommand are the Paste-source formats (Spec 109 // FR-064): a single http(s):// URL, or a single command line that isn't // JSON/TOML. Detected by DetectFormat as a fallback once every existing // config-file format has been ruled out. FormatURL ConfigFormat = "url" FormatCommand ConfigFormat = "command" )
func (ConfigFormat) String ¶
func (f ConfigFormat) String() string
String returns human-readable format name for display
type CursorAuthConfig ¶
type CursorAuthConfig struct {
ClientID string `json:"CLIENT_ID,omitempty"`
ClientSecret string `json:"CLIENT_SECRET,omitempty"`
Scopes []string `json:"scopes,omitempty"`
}
CursorAuthConfig represents OAuth configuration in Cursor.
type CursorMCPConfig ¶
type CursorMCPConfig struct {
MCPServers map[string]CursorServerConfig `json:"mcpServers"`
}
CursorMCPConfig represents the Cursor IDE configuration file structure.
type CursorParser ¶
type CursorParser struct{}
CursorParser parses Cursor IDE configuration files.
func (*CursorParser) Format ¶
func (p *CursorParser) Format() ConfigFormat
Format returns the configuration format this parser handles.
func (*CursorParser) Parse ¶
func (p *CursorParser) Parse(content []byte) ([]*ParsedServer, error)
Parse parses Cursor IDE configuration content.
type CursorServerConfig ¶
type CursorServerConfig struct {
Command string `json:"command,omitempty"`
Args []string `json:"args,omitempty"`
Env map[string]string `json:"env,omitempty"`
EnvFile string `json:"envFile,omitempty"` // Not supported, log warning
Cwd string `json:"cwd,omitempty"`
URL string `json:"url,omitempty"`
Type string `json:"type,omitempty"` // sse, streamable-http, streamableHttp
Headers map[string]string `json:"headers,omitempty"`
Auth *CursorAuthConfig `json:"auth,omitempty"`
}
CursorServerConfig represents a single server in Cursor config.
type DetectionResult ¶
type DetectionResult struct {
// Format is the detected configuration format
Format ConfigFormat
// Confidence indicates detection certainty: "high", "medium", "low"
Confidence string
// Indicators lists the detection signals found
Indicators []string
}
DetectionResult contains the result of format auto-detection.
func DetectFormat ¶
func DetectFormat(content []byte) (*DetectionResult, error)
DetectFormat identifies the configuration format from content. It tries TOML first (for Codex), then JSON (for all other formats), then falls back to the Paste-source formats (FR-064): a single http(s):// URL, or a single command line.
This fallback must stay opt-in at the Import() call site (see ImportOptions.AllowPasteFallback / DetectFormatStrict) — DetectFormat itself keeps trying it unconditionally so its own tests, and the interactive Paste tab (the one surface that previews the guess for a human to confirm before Add ever mutates anything) can call it directly.
func DetectFormatStrict ¶ added in v0.70.0
func DetectFormatStrict(content []byte) (*DetectionResult, error)
DetectFormatStrict identifies the configuration format from content, trying only TOML and JSON — it never guesses the Paste-tab URL/single-line -command fallback DetectFormat does (review round 4 F-E). Import() uses this by default and only switches to the full DetectFormat when the caller sets ImportOptions.AllowPasteFallback.
Without this split, every import surface — the CLI's `upstream import <file>`, a direct REST import call, or the general "Import config" panel — shared the exact same guess the interactive Paste tab relies on, but without that tab's preview-before-Add step: a plain one-line file that is neither JSON nor TOML (a typo, or simply the wrong file) used to return a clear "unable to detect configuration format" error; with the fallback unconditionally wired in, it was instead silently guessed as a stdio command line and — on a non-preview call — added as a real, running (quarantined) server with no confirmation step at all.
type FailedServer ¶
type FailedServer struct {
Name string `json:"name"`
Error string `json:"error"`
Details string `json:"details,omitempty"`
}
FailedServer represents a server that failed to import.
type GeminiConfig ¶
type GeminiConfig struct {
MCP *GeminiMCPGlobal `json:"mcp,omitempty"`
MCPServers map[string]GeminiServerConfig `json:"mcpServers"`
}
GeminiConfig represents the Gemini CLI configuration file structure.
type GeminiMCPGlobal ¶
type GeminiMCPGlobal struct {
Allowed []string `json:"allowed,omitempty"` // Server whitelist
Excluded []string `json:"excluded,omitempty"` // Server blacklist
ServerCommand string `json:"serverCommand,omitempty"` // Global command
}
GeminiMCPGlobal represents global MCP settings in Gemini config.
type GeminiOAuth ¶
type GeminiOAuth struct {
Enabled bool `json:"enabled,omitempty"`
ClientID string `json:"clientId,omitempty"`
ClientSecret string `json:"clientSecret,omitempty"`
Scopes []string `json:"scopes,omitempty"`
RedirectURI string `json:"redirectUri,omitempty"`
}
GeminiOAuth represents OAuth configuration in Gemini config.
type GeminiParser ¶
type GeminiParser struct{}
GeminiParser parses Gemini CLI configuration files.
func (*GeminiParser) Format ¶
func (p *GeminiParser) Format() ConfigFormat
Format returns the configuration format this parser handles.
func (*GeminiParser) Parse ¶
func (p *GeminiParser) Parse(content []byte) ([]*ParsedServer, error)
Parse parses Gemini CLI configuration content.
type GeminiServerConfig ¶
type GeminiServerConfig struct {
// Transport (httpUrl > url > command)
HTTPUrl string `json:"httpUrl,omitempty"` // HTTP streaming (priority)
URL string `json:"url,omitempty"` // SSE endpoint
Command string `json:"command,omitempty"` // Stdio
// Common
Args []string `json:"args,omitempty"`
Env map[string]string `json:"env,omitempty"`
Cwd string `json:"cwd,omitempty"`
Headers map[string]string `json:"headers,omitempty"`
Timeout int `json:"timeout,omitempty"` // Not supported
// Behavior (not supported)
Description string `json:"description,omitempty"`
Trust bool `json:"trust,omitempty"` // Security risk, ignore
IncludeTools []string `json:"includeTools,omitempty"` // Not supported
ExcludeTools []string `json:"excludeTools,omitempty"` // Not supported
// OAuth
AuthProviderType string `json:"authProviderType,omitempty"`
OAuth *GeminiOAuth `json:"oauth,omitempty"`
TargetAudience string `json:"targetAudience,omitempty"`
TargetServiceAccount string `json:"targetServiceAccount,omitempty"`
}
GeminiServerConfig represents a single server in Gemini config.
type ImportError ¶
type ImportError struct {
Type string `json:"type"`
Message string `json:"message"`
Line int `json:"line,omitempty"`
Column int `json:"column,omitempty"`
}
ImportError represents a structured error for import failures.
func (*ImportError) Error ¶
func (e *ImportError) Error() string
Error implements the error interface.
type ImportOptions ¶
type ImportOptions struct {
// Preview if true, returns preview without actually importing
Preview bool
// ServerNames if set, only import servers with these names
ServerNames []string
// FormatHint is optional format override for auto-detection
FormatHint ConfigFormat
// ExistingServers is used to check for duplicates
ExistingServers []string
// SelfListenAddrs are this mcpproxy instance's listen addresses (e.g.
// "127.0.0.1:8080"). Source entries whose URL (or stdio-bridge arg)
// addresses one of this instance's /mcp endpoints are skipped with reason
// SkipReasonSelfReference instead of being offered for import. Empty
// disables the check.
SelfListenAddrs []string
// SkipQuarantine if true, imported servers are not quarantined.
// By default, all imported servers are quarantined for security review.
SkipQuarantine bool
// AllowPasteFallback opts into DetectFormat's URL/single-command-line
// guess (FR-064) when FormatHint is empty; otherwise Import uses
// DetectFormatStrict (TOML/JSON only), returning ErrUnknownFormat for a
// plain one-liner instead of guessing at it. Only the interactive Paste
// tab sets this — it is the one surface that previews the guess for a
// human to confirm before Add ever mutates anything (review round 4
// F-E). Every other import surface (CLI `upstream import`, a direct
// REST import call, the general "Import config" panel) leaves this
// false and keeps the pre-FR-064 behavior.
AllowPasteFallback bool
// Now is the timestamp to use for Created field (default: time.Now())
Now time.Time
}
ImportOptions configures the import behavior.
type ImportResult ¶
type ImportResult struct {
// Format is the detected source format
Format ConfigFormat `json:"format"`
// FormatDisplayName is human-readable format name
FormatDisplayName string `json:"format_display_name"`
// Imported contains servers successfully imported
Imported []*ImportedServer `json:"imported"`
// Skipped contains servers that were skipped (e.g., duplicates)
Skipped []SkippedServer `json:"skipped"`
// Failed contains servers that failed to parse/map
Failed []FailedServer `json:"failed"`
// Warnings are non-fatal issues across the import
Warnings []string `json:"warnings,omitempty"`
// Summary provides counts for display
Summary ImportSummary `json:"summary"`
}
ImportResult contains the complete result of an import operation.
func Import ¶
func Import(content []byte, opts *ImportOptions) (*ImportResult, error)
Import parses configuration content and imports servers. It auto-detects the format, parses servers, maps them to MCPProxy format, and checks for duplicates.
func Preview ¶
func Preview(content []byte, opts *ImportOptions) (*ImportResult, error)
Preview is a convenience function that calls Import with Preview=true in options. It returns what would be imported without actually making changes.
type ImportSource ¶
type ImportSource struct {
// Content is the raw file content (JSON or TOML)
Content []byte
// FilePath is optional path for error messages (may be empty for pasted content)
FilePath string
// FormatHint is optional user-provided format override
FormatHint ConfigFormat
}
ImportSource represents the source content to be imported.
type ImportSummary ¶
type ImportSummary struct {
Total int `json:"total"`
Imported int `json:"imported"`
Skipped int `json:"skipped"`
Failed int `json:"failed"`
}
ImportSummary provides counts for display.
type ImportedField ¶ added in v0.70.0
type ImportedField struct {
// Name is the env var or header name.
Name string `json:"name" yaml:"name"`
// ValuePresent is true when the source config set a non-empty value.
ValuePresent bool `json:"value_present" yaml:"value_present"`
// SecretLike is a name-based heuristic (research D13):
// (?i)(token|secret|password|passwd|api[_-]?key|[_-]key$|auth|credential|
// private[_-]?key). Delegates to oauth.IsSensitiveKeyName /
// IsSensitiveHeaderName — the SAME heuristic the redaction and
// reveal-secret-headers surfaces already use, so every door agrees on
// what "looks like a secret" means.
SecretLike bool `json:"secret_like" yaml:"secret_like"`
// EmptyOrPlaceholder is true when the value is empty or an obvious
// placeholder ("YOUR_API_KEY", "<TOKEN>", "changeme", "xxx", …) — the
// case FR-040's "needs secret" tag exists to flag.
//
// Review round 4: without explicit `yaml` tags matching the `json` ones,
// gopkg.in/yaml.v3's default field-name derivation (lowercased, no word
// separators) diverged from the snake_case keys the REST DTO, swagger.yaml
// and -o json all use — `mcpproxy upstream import -o yaml` rendered
// `valuepresent`/`secretlike`/`emptyorplaceholder` instead.
EmptyOrPlaceholder bool `json:"empty_or_placeholder" yaml:"empty_or_placeholder"`
}
ImportedField is one env var or header on an imported server preview row, classified for the FR-040 "second line" without exposing the value itself (see ImportedServer.EnvFields/HeaderFields).
type ImportedServer ¶
type ImportedServer struct {
// Server is the MCPProxy-compatible server configuration
Server *config.ServerConfig
// SourceFormat indicates the original format
SourceFormat ConfigFormat
// OriginalName is the name from the source (may differ if sanitized)
OriginalName string
// FieldsSkipped lists source fields that couldn't be mapped
FieldsSkipped []string
// Warnings from parsing and mapping
Warnings []string
// Summary is the wizard/ImportServers second line: "command args…" for a
// stdio server or "url (auth-type)" for an HTTP/SSE one. Already redacted
// (oauth.LiveRedaction) — safe to display or log as-is.
Summary string `json:"summary"`
// Tags classifies Summary: any of "local process", "remote",
// "needs secret", "oauth".
Tags []string `json:"tags"`
// EnvFields / HeaderFields classify each of Server.Env/Server.Headers
// for the "needs secret" tag without exposing the values (nil when the
// server has none).
EnvFields []ImportedField `json:"env,omitempty"`
HeaderFields []ImportedField `json:"headers,omitempty"`
}
ImportedServer represents a server ready to be added to MCPProxy (mapped to ServerConfig).
type ParsedServer ¶
type ParsedServer struct {
// Name is the server identifier from the source config
Name string
// SourceFormat indicates which format this was parsed from
SourceFormat ConfigFormat
// Fields contains all parsed fields (format-specific)
// Common fields: command, args, env, url, headers, type/protocol
Fields map[string]interface{}
// Warnings contains non-fatal issues found during parsing
Warnings []string
}
ParsedServer represents a server parsed from source config, before mapping to MCPProxy format.
type Parser ¶
type Parser interface {
// Parse parses the configuration content and returns parsed servers.
Parse(content []byte) ([]*ParsedServer, error)
// Format returns the configuration format this parser handles.
Format() ConfigFormat
}
Parser is the interface that all format-specific parsers implement.
func GetParser ¶
func GetParser(format ConfigFormat) Parser
GetParser returns the appropriate parser for the given format.
type SkippedServer ¶
type SkippedServer struct {
Name string `json:"name"`
Reason string `json:"reason"` // "already_exists", "filtered_out", "invalid_name", "self_reference"
}
SkippedServer represents a server that was skipped during import.
type URLParser ¶ added in v0.70.0
type URLParser struct{}
URLParser parses a single pasted http(s):// URL into one remote server (Spec 109 FR-064). Preview never contacts the URL — Parse only validates its shape.
func (*URLParser) Format ¶ added in v0.70.0
func (p *URLParser) Format() ConfigFormat
Format implements Parser.