configimport

package
v0.73.0 Latest Latest
Warning

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

Go to latest
Published: Nov 7, 2026 License: MIT Imports: 15 Imported by: 0

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

View Source
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).

View Source
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

View Source
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

func IsNoServers(err error) bool

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

func SanitizeServerName(name string) (string, bool)

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

func SuggestNameFromCommand(parts []string) string

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

func SuggestNameFromURL(u *url.URL) string

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

func ValidServerName(name string) error

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.

func (*URLParser) Parse added in v0.70.0

func (p *URLParser) Parse(content []byte) ([]*ParsedServer, error)

Parse implements Parser.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL