fastmcp-rs Prototype

This crate hosts an experimental Rust reimplementation of the FastMCP server. The goal is to provide feature parity with the core server ergonomics-tools, resources, prompts, and transports-using idiomatic Rust.

Feature Targets

• FastMcpServer core orchestrator storing metadata, registry state, and hooks
• ToolManager for registering async tool handlers with JSON schema metadata and annotations
• ResourceManager for static and dynamic resources plus content streaming
• PromptManager for templated messages following MCP semantics
• HTTP transport built on axum exposing health, metadata, tool/resource/prompt operations
• SSE transport with a message gateway for long-lived clients
• Streamable HTTP sessions for bidirectional, chunked command responses
• STDIO transport that accepts JSON commands for shell-based MCP integrations
• Extensible middleware/auth hooks mirroring Python counterparts (scaffolding only in prototype)

Module Layout

src/
  lib.rs                # re-exports and FastMcpServer entry point
  command.rs            # shared command envelope + dispatch logic
  server.rs             # FastMcpServer, configuration, metadata
  tool.rs               # ToolDefinition, ToolRegistry, ToolInvocation
  resource.rs           # ResourceDefinition, ResourceManager
  prompt.rs             # PromptDefinition, PromptManager, templating
  error.rs              # FastMcpError hierarchy using thiserror
  stdio.rs              # STDIO transport runtime
  http/
    mod.rs              # HTTP/SSE/streamable HTTP server builder and handlers

Examples

cargo run --example simple_add
cargo run --example fetch_url

• simple_add exposes an add tool over STDIO and demonstrates a basic prompt.
• fetch_url spins up the HTTP stack and streams responses from a fetch_url tool.

Macro Ergonomics

This crate now provides macros to reduce boilerplate when defining and registering tools, resources, and prompts. Import them via use fastmcp_rs::macros::*;.

Example — define and register a tool (JSON schema via parameters_json):

use fastmcp_rs::{FastMcpServer, macros::*, tool::ToolResponse};
use serde_json::{Value, json};

let server = FastMcpServer::builder().name("Demo").build().into_shared();

mcp_register_tools!(server, [
    mcp_tool! {
        name: "echo",
        handler: |_, payload: Value| async move {
            Ok(mcp_response!([ mcp_text!(payload.to_string()) ]))
        },
        description: "Echoes the payload",
        parameters_json: { "type": "object" },
        annotations: { "category": json!("demo") },
    }
]);

Attribute-style tool definition:

use serde_json::{json, Value};
use fastmcp_rs::{FastMcpServer, mcp_register_tools, mcp_response, mcp_text, tool::ToolResponse};

// Path-qualified attribute avoids name clash with `mcp_tool!`
#[fastmcp_rs_macros::mcp_tool(
    name = "add",
    description = "Adds two numbers",
    parameters_json(
        "type": "object",
        "required": ["a", "b"],
        "properties": { "a": { "type": "number" }, "b": { "type": "number" } }
    ),
    annotations(category = json!("math"))
)]
async fn add(_: fastmcp_rs::InvocationContext, payload: Value) -> fastmcp_rs::Result<ToolResponse> {
    let a = payload.get("a").and_then(Value::as_f64).unwrap_or(0.0);
    let b = payload.get("b").and_then(Value::as_f64).unwrap_or(0.0);
    Ok(mcp_response!([ mcp_text!(format!("{} + {} = {}", a, b, a + b)) ]))
}

let server = FastMcpServer::builder().name("AttrDemo").build().into_shared();
// Register via generated factory function
mcp_register_tools!(server, [ add_tool() ]);
// Or call the generated helper directly: add_register(&server)?;

Supported attribute keys: name, description, summary, parameters (expr of type serde_json::Value), parameters_json(...), and annotations(key = expr, ...). Two helpers are generated: <fn>_tool() and <fn>_register(server).

Example — single-message text prompt:

mcp_register_prompts!(server, [
    mcp_prompt_text! {
        name: "welcome",
        role: "system",
        text: "Hello {{ user }}",
        description: "Greets a user",
        parameters: json!({
            "type": "object",
            "required": ["user"],
            "properties": { "user": { "type": "string" } }
        }),
    }
]);

Resources (static and dynamic):

use fastmcp_rs::resource::ResourceContent;

mcp_register_resources!(server, [
    mcp_resource_static! {
        uri: "resource://hello",
        content: ResourceContent::text("hello world"),
        description: "Simple text resource",
        annotations: { "kind": json!("demo") },
    }
    ,
    mcp_resource_dynamic! {
        uri: "resource://time",
        resolver: MyResolver {},
        description: "Current server time"
    }
]);

Server builder shortcut:

let server = mcp_server!{
  name: "Demo",
  instructions: "Use the provided tools",
  tool_duplicates: fastmcp_rs::tool::DuplicateBehavior::Warn,
};

Roadmap

• Implement registries and domain models with strong typing and serde support
• Lift registries into FastMcpServer
• Expose HTTP + SSE transports with tokio/axum
• Provide STDIO and streamable HTTP transports plus integration tests
• Extend transports with auth, streamable HTTP parity features, and document remaining gaps (sampling, middleware)

发布准备（Release Prep）

• 仓库地址：https://gitee.com/luzhihaoTestingLab/fastmcp-rust.git
• 当前版本：0.2.0
• 子 crate：fastmcp-rs-macros 版本 0.2.0
• 文档入口（预留）：https://docs.rs/fastmcp-rs、https://docs.rs/fastmcp-rs-macros
• License：MIT（已在 Cargo.toml 指定）
• 特性（features）：
  • auto-register：启用后，使用 #[mcp_tool] 的函数会自动注册到 FastMcpServer，避免显式 mcp_register_tools!。

版本约定（Versioning）

• 0.2.x：新增属性宏 #[mcp_tool] 与 auto-register 可选特性，示例与文档更新。
• 0.1.x：核心服务、工具/资源/提示词注册与 HTTP/STDIO 传输原型。

发布清单（Checklist）

• Cargo.toml：主 crate 与子 crate 的版本、仓库、主页、文档字段完整。
• README：包含使用示例、宏说明与发布信息。
• 示例：simple_add、fetch_url、resources 可独立构建；在 Windows 环境下，避免一次性 --examples 链接锁问题。
• 特性：auto-register 已文档化并在示例中兼容处理（避免重复注册）。