Documentation
¶
Overview ¶
Package mcproutes defines AppTheory's versioned MCP route algebra.
Index ¶
- Constants
- func AuthorizationAuthorizePathForResourcePath(resourcePath string) string
- func AuthorizationRegisterPathForResourcePath(resourcePath string) string
- func AuthorizationServerPathForResourcePath(resourcePath string) string
- func AuthorizationServerSuffixPathForResourcePath(resourcePath string) string
- func AuthorizationTokenPathForResourcePath(resourcePath string) string
- func CallbackPathForConfiguredPath(configured string) (string, bool)
- func NormalizeCallbackPath(rawPath string) (string, bool)
- func ProtectedResourcePathForResourcePath(resourcePath string) string
- func ProtectedResourcePathFromMCPPath(mcpPath string) string
- func ResourcePathFromProtectedResourcePath(protectedResourcePath string) (string, error)
- type EndpointKind
- type EndpointPath
- func (e EndpointPath) MCPPath() (string, error)
- func (e EndpointPath) OAuthAuthorizationServerPath() (string, error)
- func (e EndpointPath) OAuthAuthorizationServerSuffixPath() (string, error)
- func (e EndpointPath) OAuthAuthorizePath() (string, error)
- func (e EndpointPath) OAuthRegisterPath() (string, error)
- func (e EndpointPath) OAuthTokenPath() (string, error)
- func (e EndpointPath) ProtectedResourcePath() (string, error)
- func (e EndpointPath) Validate() error
- type EndpointTemplate
- type IssuerMode
- type OAuthDiscoveryTemplate
- type OAuthFacadeTemplate
- type StageGlobalRoute
Constants ¶
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" )
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 ¶
AuthorizationAuthorizePathForResourcePath derives the authorization facade path.
func AuthorizationRegisterPathForResourcePath ¶
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 ¶
AuthorizationServerPathForResourcePath derives the canonical RFC 8414 discovery path.
func AuthorizationServerSuffixPathForResourcePath ¶
AuthorizationServerSuffixPathForResourcePath derives the suffix-compatible RFC 8414 discovery path.
func AuthorizationTokenPathForResourcePath ¶
AuthorizationTokenPathForResourcePath derives the token facade path.
func CallbackPathForConfiguredPath ¶
CallbackPathForConfiguredPath resolves the effective callback path for a configuration value, falling back to the contract default when unset.
func NormalizeCallbackPath ¶
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 ¶
ProtectedResourcePathForResourcePath derives an RFC 9728 protected-resource path.
func ProtectedResourcePathFromMCPPath ¶
ProtectedResourcePathFromMCPPath derives the protected-resource path for an MCP 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 ¶
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.