mcproutes

package
v7.4.0 Latest Latest
Warning

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

Go to latest
Published: Nov 17, 2026 License: Apache-2.0 Imports: 4 Imported by: 0

Documentation

Overview

Package mcproutes defines AppTheory's versioned MCP route algebra.

Index

Constants

View Source
const (
	// ContractVersion is the MCP route-algebra contract implemented by this package.
	//
	// v2 is a superset of v1: the four canonical MCP patterns and the v1
	// derivations (protected resource, canonical/suffix discovery, authorize,
	// token) are unchanged. v2 adds the derived register path per kind, one
	// stage-global callback path, and the IssuerMode vocabulary for per-route
	// issuer/resource derivation.
	ContractVersion = "m17.mcp-route-algebra/v2"
	// ContractVersionV1 is the superseded read contract retained for compatibility.
	ContractVersionV1 = "m17.mcp-route-algebra/v1"
	// ParamClientNamespace is the canonical client-namespace route parameter name.
	ParamClientNamespace = "client_namespace"
	// ParamPartnerID is the canonical partner route parameter name.
	ParamPartnerID = "partner_id"
	// ParamAgentID is the canonical agent route parameter name.
	ParamAgentID = "agent_id"

	// ProtectedResourcePrefix is the RFC 9728 protected-resource metadata prefix.
	ProtectedResourcePrefix = "/.well-known/oauth-protected-resource"
	// AuthorizationServerPrefix is the RFC 8414 authorization-server metadata prefix.
	AuthorizationServerPrefix = "/.well-known/oauth-authorization-server"

	// DefaultCallbackPath is the stage-global upstream OAuth callback path.
	//
	// The callback is correlated by the single-use upstream state the facade
	// minted, so one stage-global route is sufficient and no per-kind callback
	// multiplies.
	DefaultCallbackPath = "/_oauth/mcp/callback"
	// CallbackPatternKey names the stage-global callback route in the route model.
	CallbackPatternKey = "upstream_callback"
)
View Source
const (
	// NamespaceMCPPattern is the canonical namespace MCP route pattern.
	NamespaceMCPPattern = "/{client_namespace}/mcp"
	// PartnerNamespaceMCPPattern is the canonical partner-scoped namespace MCP route pattern.
	PartnerNamespaceMCPPattern = "/{client_namespace}/partners/{partner_id}/mcp"
	// AgentMCPPattern is the canonical agent MCP route pattern.
	AgentMCPPattern = "/{client_namespace}/agents/{agent_id}/mcp"
	// PartnerAgentMCPPattern is the canonical partner-scoped agent MCP route pattern.
	PartnerAgentMCPPattern = "/{client_namespace}/partners/{partner_id}/agents/{agent_id}/mcp"
)

Variables

This section is empty.

Functions

func AuthorizationAuthorizePathForResourcePath

func AuthorizationAuthorizePathForResourcePath(resourcePath string) string

AuthorizationAuthorizePathForResourcePath derives the authorization facade path.

func AuthorizationRegisterPathForResourcePath

func AuthorizationRegisterPathForResourcePath(resourcePath string) string

AuthorizationRegisterPathForResourcePath derives the RFC 7591 dynamic-client registration facade path mounted beside the canonical RFC 8414 discovery path.

The routed discovery document advertises exactly this path as registration_endpoint, so the advertised URL and the mounted route cannot drift.

func AuthorizationServerPathForResourcePath

func AuthorizationServerPathForResourcePath(resourcePath string) string

AuthorizationServerPathForResourcePath derives the canonical RFC 8414 discovery path.

func AuthorizationServerSuffixPathForResourcePath

func AuthorizationServerSuffixPathForResourcePath(resourcePath string) string

AuthorizationServerSuffixPathForResourcePath derives the suffix-compatible RFC 8414 discovery path.

func AuthorizationTokenPathForResourcePath

func AuthorizationTokenPathForResourcePath(resourcePath string) string

AuthorizationTokenPathForResourcePath derives the token facade path.

func CallbackPathForConfiguredPath

func CallbackPathForConfiguredPath(configured string) (string, bool)

CallbackPathForConfiguredPath resolves the effective callback path for a configuration value, falling back to the contract default when unset.

func NormalizeCallbackPath

func NormalizeCallbackPath(rawPath string) (string, bool)

NormalizeCallbackPath validates and normalizes an absolute callback path.

The path must be absolute, contain no query or fragment, and must not use a dot segment. It is normalized with the same rules as every other route path.

func ProtectedResourcePathForResourcePath

func ProtectedResourcePathForResourcePath(resourcePath string) string

ProtectedResourcePathForResourcePath derives an RFC 9728 protected-resource path.

func ProtectedResourcePathFromMCPPath

func ProtectedResourcePathFromMCPPath(mcpPath string) string

ProtectedResourcePathFromMCPPath derives the protected-resource path for an MCP path.

func ResourcePathFromProtectedResourcePath

func ResourcePathFromProtectedResourcePath(protectedResourcePath string) (string, error)

ResourcePathFromProtectedResourcePath recovers a resource path from its RFC 9728 metadata path.

Types

type EndpointKind

type EndpointKind string

EndpointKind identifies a canonical MCP endpoint shape.

const (
	// EndpointKindNamespace identifies a namespace MCP endpoint.
	EndpointKindNamespace EndpointKind = "namespace"
	// EndpointKindPartnerNamespace identifies a partner-scoped namespace MCP endpoint.
	EndpointKindPartnerNamespace EndpointKind = "partner_namespace"
	// EndpointKindAgent identifies an agent MCP endpoint.
	EndpointKindAgent EndpointKind = "agent"
	// EndpointKindPartnerAgent identifies a partner-scoped agent MCP endpoint.
	EndpointKindPartnerAgent EndpointKind = "partner_agent"
)

type EndpointPath

type EndpointPath struct {
	Kind            EndpointKind
	ClientNamespace string
	PartnerID       string
	AgentID         string
}

EndpointPath is a concrete canonical MCP endpoint.

func ParseMCPPath

func ParseMCPPath(rawPath string) (EndpointPath, error)

ParseMCPPath parses a concrete MCP path after contract normalization.

func (EndpointPath) MCPPath

func (e EndpointPath) MCPPath() (string, error)

MCPPath builds the concrete MCP path for the endpoint.

func (EndpointPath) OAuthAuthorizationServerPath

func (e EndpointPath) OAuthAuthorizationServerPath() (string, error)

OAuthAuthorizationServerPath builds the endpoint's canonical RFC 8414 discovery path.

func (EndpointPath) OAuthAuthorizationServerSuffixPath

func (e EndpointPath) OAuthAuthorizationServerSuffixPath() (string, error)

OAuthAuthorizationServerSuffixPath builds the endpoint's suffix-compatible RFC 8414 discovery path.

func (EndpointPath) OAuthAuthorizePath

func (e EndpointPath) OAuthAuthorizePath() (string, error)

OAuthAuthorizePath builds the endpoint's authorization facade path.

func (EndpointPath) OAuthRegisterPath

func (e EndpointPath) OAuthRegisterPath() (string, error)

OAuthRegisterPath builds the endpoint's dynamic-client registration path.

func (EndpointPath) OAuthTokenPath

func (e EndpointPath) OAuthTokenPath() (string, error)

OAuthTokenPath builds the endpoint's token facade path.

func (EndpointPath) ProtectedResourcePath

func (e EndpointPath) ProtectedResourcePath() (string, error)

ProtectedResourcePath builds the endpoint's RFC 9728 protected-resource path.

func (EndpointPath) Validate

func (e EndpointPath) Validate() error

Validate verifies kind-to-identifier consistency and path-segment safety.

type EndpointTemplate

type EndpointTemplate struct {
	Kind                  EndpointKind
	MCPPattern            string
	ProtectedResourcePath string
}

EndpointTemplate describes a canonical MCP route pattern and its protected-resource route.

func SupportedEndpointTemplates

func SupportedEndpointTemplates() []EndpointTemplate

SupportedEndpointTemplates returns every canonical MCP endpoint template in contract order.

type IssuerMode

type IssuerMode string

IssuerMode selects how the facade derives each route's issuer and resource.

const (
	// IssuerModeFamily advertises one family-wide issuer for the whole facade.
	// This is the current behavior and remains for single-tenant/root-only
	// deployments.
	IssuerModeFamily IssuerMode = "family"
	// IssuerModeRoute makes each route its own authorization-server issuer: the
	// route URL. Required for single-domain proxying of an upstream provider and
	// for RFC 9207 iss-aware clients.
	IssuerModeRoute IssuerMode = "route"
)

func SupportedIssuerModes

func SupportedIssuerModes() []IssuerMode

SupportedIssuerModes returns the closed IssuerMode vocabulary in contract order.

type OAuthDiscoveryTemplate

type OAuthDiscoveryTemplate struct {
	Kind             EndpointKind
	CanonicalPattern string
	SuffixPattern    string
}

OAuthDiscoveryTemplate describes canonical and suffix-compatible discovery routes.

func SupportedOAuthDiscoveryTemplates

func SupportedOAuthDiscoveryTemplates() []OAuthDiscoveryTemplate

SupportedOAuthDiscoveryTemplates returns every canonical OAuth discovery template in contract order.

type OAuthFacadeTemplate

type OAuthFacadeTemplate struct {
	Kind             EndpointKind
	AuthorizePattern string
	TokenPattern     string
	RegisterPattern  string
}

OAuthFacadeTemplate describes the authorization facade routes for an MCP endpoint kind.

func SupportedOAuthFacadeTemplates

func SupportedOAuthFacadeTemplates() []OAuthFacadeTemplate

SupportedOAuthFacadeTemplates returns every canonical OAuth facade template in contract order.

type StageGlobalRoute

type StageGlobalRoute struct {
	Name    string
	Pattern string
	Methods []string
}

StageGlobalRoute describes one route that is not derived from an MCP endpoint kind but is installed once per deployment.

func SupportedStageGlobalRoutes

func SupportedStageGlobalRoutes() []StageGlobalRoute

SupportedStageGlobalRoutes returns the stage-global route inventory in contract order.

v2 adds exactly one stage-global route: the upstream OAuth callback. The callback path is overridable (FacadeConfig.UpstreamCallbackPath); this returns the contract default.

Jump to

Keyboard shortcuts

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