mod protocol;
mod tool;
#[cfg(feature = "mcp-openapi")]
pub mod openapi;
use std::fmt;
use std::sync::Arc;
use std::time::Duration;
use lambda_http::http::{HeaderMap, HeaderValue, Method, StatusCode, header};
use serde_json::{Map, Value, json};
pub use protocol::PROTOCOL_VERSION;
pub use tool::{INVALID_ARGUMENTS, Tool};
use self::protocol::{Message, Reply};
use crate::http::{
Admission, AdmitAll, Api, DEFAULT_BODY_LIMIT, ErrorRenderer, Failure, HttpResponse, Policy,
Request, codes, literal,
};
use crate::{Context, Invocation, RuntimeError};
pub const MAX_TOOLS: usize = 128;
pub const CALL_MARGIN: Duration = Duration::from_secs(1);
const CACHE_TTL_MS: u64 = 300_000;
const METADATA_PATH: &str = "/.well-known/oauth-protected-resource";
type Visible<Scope> = Box<dyn Fn(&str, &Scope) -> bool + Send + Sync>;
pub struct Server<App, P: Policy, A = AdmitAll> {
name: &'static str,
version: &'static str,
policy: Arc<P>,
admission: Arc<A>,
instructions: Option<String>,
origins: Arc<[String]>,
resource: Option<ProtectedResource>,
body_limit: usize,
tools: Vec<Tool<App, P::Scope>>,
visible: Option<Visible<P::Scope>>,
}
impl<App, P> Server<App, P>
where
App: Send + Sync + 'static,
P: Policy,
{
#[must_use]
pub fn new(name: &'static str, version: &'static str, policy: P) -> Self {
Self {
name,
version,
policy: Arc::new(policy),
admission: Arc::new(AdmitAll),
instructions: None,
origins: Arc::from([]),
resource: None,
body_limit: DEFAULT_BODY_LIMIT,
tools: Vec::new(),
visible: None,
}
}
}
impl<App, P, A> Server<App, P, A>
where
App: Send + Sync + 'static,
P: Policy,
A: Admission,
{
#[must_use]
pub fn admission<B: Admission>(self, admission: B) -> Server<App, P, B> {
Server {
name: self.name,
version: self.version,
policy: self.policy,
admission: Arc::new(admission),
instructions: self.instructions,
origins: self.origins,
resource: self.resource,
body_limit: self.body_limit,
tools: self.tools,
visible: self.visible,
}
}
#[must_use]
pub fn instructions(mut self, instructions: impl Into<String>) -> Self {
self.instructions = Some(instructions.into());
self
}
#[must_use]
pub fn allow_origins(mut self, origins: impl IntoIterator<Item = impl Into<String>>) -> Self {
self.origins = origins.into_iter().map(Into::into).collect();
self
}
#[must_use]
pub fn protected_resource(mut self, resource: ProtectedResource) -> Self {
self.resource = Some(resource);
self
}
#[must_use]
pub fn body_limit(mut self, bytes: usize) -> Self {
self.body_limit = bytes;
self
}
#[must_use]
pub fn tool(mut self, tool: Tool<App, P::Scope>) -> Self {
let name = tool.name();
assert!(valid_name(name), "invalid tool name {name:?}");
assert!(
self.tools.iter().all(|other| other.name() != name),
"duplicate tool name {name:?}"
);
assert!(self.tools.len() < MAX_TOOLS, "more than {MAX_TOOLS} tools");
self.tools.push(tool);
self
}
#[must_use]
pub fn visible(
mut self,
visible: impl Fn(&str, &P::Scope) -> bool + Send + Sync + 'static,
) -> Self {
self.visible = Some(Box::new(visible));
self
}
pub async fn handle(&self, app: Arc<App>, request: lambda_http::Request) -> HttpResponse {
let serve = |app, inbound, context| self.serve(app, inbound, context);
self.api().handle(app, request, &decode, &serve).await
}
pub async fn run(self, app: Arc<App>) -> Result<(), RuntimeError> {
let server = &self;
self.api()
.run(app, decode, move |app, inbound, context| {
server.serve(app, inbound, context)
})
.await
}
fn api(&self) -> Api<Gate<P>, RpcErrors, Origins<A>> {
let challenge = self
.resource
.as_ref()
.map_or_else(|| "Bearer".to_owned(), ProtectedResource::challenge);
Api::new(
self.name,
Gate(Arc::clone(&self.policy)),
RpcErrors { challenge },
)
.admission(Origins {
allowed: Arc::clone(&self.origins),
then: Arc::clone(&self.admission),
})
.body_limit(self.body_limit)
}
async fn serve(
&self,
app: Arc<App>,
inbound: Inbound,
context: Context<Target<P::Scope>>,
) -> Result<HttpResponse, Failure> {
let invocation = context.invocation().clone();
match context.into_scope() {
Target::Endpoint(scope) => Ok(self.endpoint(app, inbound, invocation, scope).await),
Target::Metadata => match &self.resource {
Some(resource) => Ok(literal(
StatusCode::OK,
"application/json",
resource.document().to_string(),
)),
None => Err(Failure::new(
StatusCode::NOT_FOUND,
codes::NOT_FOUND,
"Not found",
)),
},
Target::Elsewhere => Err(Failure::new(
StatusCode::METHOD_NOT_ALLOWED,
codes::METHOD_NOT_ALLOWED,
"The MCP endpoint accepts POST",
)
.with_header("allow", "POST")),
}
}
async fn endpoint(
&self,
app: Arc<App>,
inbound: Inbound,
invocation: Invocation,
scope: P::Scope,
) -> HttpResponse {
let message = match protocol::parse(&inbound.body) {
Ok(message) => message,
Err(reply) => return reply.into_response(),
};
let Some(id) = message.id.clone() else {
return Reply::accepted().into_response();
};
if let Err(reply) = protocol::validate(&inbound.headers, &message) {
return reply.into_response();
}
let authorization = inbound
.headers
.get(header::AUTHORIZATION)
.and_then(|value| value.to_str().ok())
.map(str::to_owned);
self.answer(app, message, id, invocation, scope, authorization)
.await
.into_response()
}
async fn answer(
&self,
app: Arc<App>,
mut message: Message,
id: Value,
invocation: Invocation,
scope: P::Scope,
authorization: Option<String>,
) -> Reply {
let server = json!({ "name": self.name, "version": self.version });
let method = std::mem::take(&mut message.method);
let mut result = Map::new();
match method.as_str() {
"server/discover" => {
result.insert("supportedVersions".into(), json!([PROTOCOL_VERSION]));
result.insert("capabilities".into(), json!({ "tools": {} }));
if let Some(instructions) = &self.instructions {
result.insert("instructions".into(), json!(instructions));
}
result.insert("ttlMs".into(), json!(CACHE_TTL_MS));
result.insert("cacheScope".into(), json!("public"));
}
"ping" => {}
"tools/list" => {
let tools: Vec<&Value> = self
.tools
.iter()
.filter(|tool| self.shows(tool, &scope))
.map(|tool| &tool.definition)
.collect();
let shared = if self.visible.is_some() {
"private"
} else {
"public"
};
result.insert("tools".into(), json!(tools));
result.insert("ttlMs".into(), json!(CACHE_TTL_MS));
result.insert("cacheScope".into(), json!(shared));
}
"tools/call" => {
match self
.call(app, message, &id, invocation, scope, authorization)
.await
{
Ok(called) => result = called,
Err(reply) => return reply,
}
}
method => {
return Reply::error(
StatusCode::NOT_FOUND,
Some(id),
protocol::METHOD_NOT_FOUND,
format!("Method not found: {method}"),
None,
);
}
}
Reply::result(id, &server, result)
}
fn shows(&self, tool: &Tool<App, P::Scope>, scope: &P::Scope) -> bool {
self.visible
.as_ref()
.is_none_or(|visible| visible(tool.name(), scope))
}
async fn call(
&self,
app: Arc<App>,
mut message: Message,
id: &Value,
mut invocation: Invocation,
scope: P::Scope,
authorization: Option<String>,
) -> Result<Map<String, Value>, Reply> {
let invalid = |status, text: &str| {
Reply::error(
status,
Some(id.clone()),
protocol::INVALID_PARAMS,
text,
None,
)
};
let name = message.text("name").unwrap_or_default().to_owned();
let Some(tool) = self
.tools
.iter()
.find(|tool| tool.name() == name && self.shows(tool, &scope))
else {
return Err(invalid(StatusCode::OK, &format!("Unknown tool: {name}")));
};
let arguments = match message.params.remove("arguments") {
None | Some(Value::Null) => Map::new(),
Some(Value::Object(arguments)) => arguments,
Some(_) => {
return Err(invalid(
StatusCode::BAD_REQUEST,
"params.arguments must be an object",
));
}
};
let deadline = invocation.deadline.with_margin(CALL_MARGIN);
invocation.deadline = deadline;
let work = (tool.run)(
app,
arguments,
Context::new(invocation, scope),
authorization,
);
Ok(tool::result(&name, deadline.run(work).await))
}
}
impl<App, P: Policy, A> fmt::Debug for Server<App, P, A> {
fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
f.debug_struct("Server")
.field("name", &self.name)
.field("version", &self.version)
.field("origins", &self.origins)
.field("resource", &self.resource)
.field("body_limit", &self.body_limit)
.field("tools", &self.tools)
.field("visible", &self.visible.is_some())
.finish_non_exhaustive()
}
}
fn valid_name(name: &str) -> bool {
(1..=128).contains(&name.len())
&& name
.bytes()
.all(|byte| byte.is_ascii_alphanumeric() || matches!(byte, b'_' | b'-' | b'.'))
}
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct ProtectedResource {
resource: String,
authorization_servers: Vec<String>,
scopes: Vec<String>,
}
impl ProtectedResource {
#[must_use]
pub fn new(
resource: impl Into<String>,
authorization_servers: impl IntoIterator<Item = impl Into<String>>,
) -> Self {
Self {
resource: resource.into(),
authorization_servers: authorization_servers.into_iter().map(Into::into).collect(),
scopes: Vec::new(),
}
}
#[must_use]
pub fn scopes(mut self, scopes: impl IntoIterator<Item = impl Into<String>>) -> Self {
self.scopes = scopes.into_iter().map(Into::into).collect();
self
}
fn document(&self) -> Value {
let mut document = json!({
"resource": self.resource,
"authorization_servers": self.authorization_servers,
"bearer_methods_supported": ["header"],
});
if !self.scopes.is_empty() {
document["scopes_supported"] = json!(self.scopes);
}
document
}
fn metadata_url(&self) -> String {
let resource = self.resource.trim_end_matches('/');
let host = resource.find("://").map_or(0, |scheme| scheme + 3);
let path = resource[host..]
.find('/')
.map_or(resource.len(), |at| host + at);
format!("{}{METADATA_PATH}{}", &resource[..path], &resource[path..])
}
fn challenge(&self) -> String {
let mut challenge = format!("Bearer resource_metadata=\"{}\"", self.metadata_url());
if !self.scopes.is_empty() {
challenge.push_str(&format!(", scope=\"{}\"", self.scopes.join(" ")));
}
challenge
}
}
struct Inbound {
headers: HeaderMap,
body: Vec<u8>,
}
fn decode(request: &Request<'_>) -> Result<Inbound, Failure> {
Ok(Inbound {
headers: request.headers().clone(),
body: request.raw_body().to_vec(),
})
}
enum Target<Scope> {
Endpoint(Scope),
Metadata,
Elsewhere,
}
struct Gate<P>(Arc<P>);
impl<P: Policy> Policy for Gate<P> {
type Scope = Target<P::Scope>;
async fn authorize(
&self,
request: &Request<'_>,
invocation: &Invocation,
) -> Result<Self::Scope, Failure> {
let path = request.native().uri().path();
match *request.method() {
Method::POST => self
.0
.authorize(request, invocation)
.await
.map(Target::Endpoint),
Method::GET if is_metadata(path) => Ok(Target::Metadata),
_ => Ok(Target::Elsewhere),
}
}
}
fn is_metadata(path: &str) -> bool {
path.strip_prefix(METADATA_PATH)
.is_some_and(|rest| rest.is_empty() || rest.starts_with('/'))
}
struct Origins<A> {
allowed: Arc<[String]>,
then: Arc<A>,
}
impl<A: Admission> Admission for Origins<A> {
async fn check(
&self,
request: &Request<'_>,
invocation: &Invocation,
) -> Result<Vec<(String, String)>, Failure> {
match request.header("origin") {
Some(origin) if !self.allowed.iter().any(|allowed| allowed == origin) => {
Err(Failure::new(
StatusCode::FORBIDDEN,
codes::ORIGIN_NOT_ALLOWED,
"Origin not allowed",
))
}
_ => self.then.check(request, invocation).await,
}
}
}
struct RpcErrors {
challenge: String,
}
impl ErrorRenderer for RpcErrors {
fn render(&self, failure: &Failure) -> HttpResponse {
let code = if failure.is_server_error() {
protocol::INTERNAL_ERROR
} else {
protocol::INVALID_REQUEST
};
let body = json!({
"jsonrpc": "2.0",
"error": { "code": code, "message": failure.public_message() }
});
let mut response = literal(failure.status(), "application/json", body.to_string());
let headers: HeaderMap = failure.headers().iter().cloned().collect();
response.headers_mut().extend(headers);
if failure.status() == StatusCode::UNAUTHORIZED {
let challenge = HeaderValue::try_from(self.challenge.as_str())
.unwrap_or(HeaderValue::from_static("Bearer"));
response
.headers_mut()
.insert(header::WWW_AUTHENTICATE, challenge);
}
response
}
}