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 已文档化并在示例中兼容处理（避免重复注册）。

fastmcp-rs 0.2.0