Nexs Fastmcp
No description available
Ask AI about Nexs Fastmcp
Powered by Claude Β· Grounded in docs
I know everything about Nexs Fastmcp. Ask me about installation, configuration, usage, or troubleshooting.
0/500
Reviews
Documentation
NexsFastMCP
High-performance Go framework for building Model Context Protocol (MCP) servers β protocol version
2025-06-18.
Overview
NexsFastMCP is a framework for building MCP servers in Go with a fluent builder API, reflection-based JSON Schema generation, and support for multiple transports (Stdio, HTTP Streamable, SSE).
It lets you expose tools, resources, and prompts to any MCP-compatible client β Claude Desktop, VS Code with Copilot, or any custom client β with minimal boilerplate.
package main
import (
"context"
"fmt"
"log"
nexsfastmcp "github.com/fsvxavier/nexs-fastmcp"
"github.com/fsvxavier/nexs-fastmcp/pkg/tools"
)
type GreetInput struct {
Name string `json:"name" jsonschema_description:"Name of the person to greet"`
}
func main() {
srv := nexsfastmcp.New("hello-world",
nexsfastmcp.WithVersion("1.0.0"),
nexsfastmcp.WithInstructions("A demo server that greets users."),
)
srv.Tool("greet",
func(_ context.Context, in GreetInput) (string, error) {
if in.Name == "" {
return "", fmt.Errorf("name is required")
}
return fmt.Sprintf("Hello, %s! Welcome to NexsFastMCP", in.Name), nil
},
tools.WithDescription("Greets a person by name"),
tools.WithAnnotations(tools.ReadOnly()),
)
log.Fatal(srv.RunStdio(context.Background()))
}
Table of Contents
- Features
- Installation
- Quick Start
- Architecture
- Transports
- Examples
- Documentation
- Dependencies
- Contributing
Features
| Feature | Description |
|---|---|
| Fluent Builder API | Chain .Tool(), .Resource(), .Prompt() for concise server setup |
| Reflection-based Schemas | Automatic JSON Schema generation from Go structs via struct tags |
| Multiple Transports | Stdio, HTTP Streamable (MCP 2025-06-18), and SSE in a single binary |
| Type-safe Generics | Registry[T] provides compile-time safety for components |
| Observability | Structured logging (zap), Prometheus metrics, OpenTelemetry tracing, health checks |
| Lifespan Management | Shared state initialization and teardown at server startup/shutdown |
| MCP Client | Built-in client for programmatically calling other MCP servers |
| Functional Options | WithDescription(), WithTimeout(), WithAnnotations(), etc. |
| Zero-config Defaults | Sensible defaults for everything β override only what you need |
Installation
go get github.com/fsvxavier/nexs-fastmcp
Requirements: Go 1.23+
Quick Start
1. Create a server with a tool
srv := nexsfastmcp.New("my-server", nexsfastmcp.WithVersion("1.0.0"))
srv.Tool("add",
func(_ context.Context, in struct {
A float64 `json:"a"`
B float64 `json:"b"`
}) (float64, error) {
return in.A + in.B, nil
},
tools.WithDescription("Adds two numbers"),
)
2. Add a resource
srv.TextResource("docs://readme",
"# My Server\nThis server does math.",
resources.WithDescription("Server documentation"),
)
3. Add a prompt
srv.Prompt("summarize",
func(_ context.Context, in struct {
Topic string `json:"topic"`
}) ([]protocol.Message, error) {
return []protocol.Message{
protocol.UserTextMessage(fmt.Sprintf("Summarize: %s", in.Topic)),
}, nil
},
)
4. Run
// Stdio β for Claude Desktop and VS Code
log.Fatal(srv.RunStdio(context.Background()))
// HTTP β for web clients
log.Fatal(srv.RunHTTP(context.Background(), ":8080"))
Architecture
βββββββββββββββββββββββββββββββββββββββββββββββββββ
β FastMCP (Builder) β
β .Tool() .Resource() .Prompt() .RunStdio/HTTP() β
ββββββββββββββββββββββββ¬βββββββββββββββββββββββββββ
β
ββββββββββΌβββββββββ
β Server β
β (Orchestrator) β
βββββ¬βββββ¬βββββ¬ββββ
βββββββββ β βββββββββ
βββββββΌββββββ ββββββΌβββββ ββββββΌββββββ
β Registry β βRegistry β β Registry β
β <Tool> β β<Resourceβ β <Prompt> β
βββββββ¬ββββββ ββββββ¬βββββ ββββββ¬ββββββ
β β β
βββββββΌβββββββββββββΌββββββββββββΌβββββββ
β Handler (JSON-RPC) β
ββββββββββββββββββ¬βββββββββββββββββββββ
β
βββββββββββββΌββββββββββββ
ββββββΌβββββ ββββββΌβββββ βββββΌβββββ
β Stdio β β HTTP β β SSE β
βTransportβ βTransportβ βTransportβ
βββββββββββ βββββββββββ ββββββββββ
Key packages:
| Package | Responsibility |
|---|---|
nexsfastmcp (root) | Builder API entrypoint β New(), Tool(), Resource(), Prompt(), Run*() |
pkg/tools | Tool registration, schema generation, handler invocation |
pkg/resources | Static resources and URI template resources |
pkg/prompts | Prompt templates with typed arguments |
pkg/context | Context helpers β session ID, logger, lifespan state |
pkg/lifespan | Server lifecycle hooks with shared state |
pkg/observability | Logging (zap), metrics (Prometheus), tracing (OpenTelemetry), health |
pkg/transport/http | HTTP Streamable transport (MCP 2025-06-18) |
client | MCP client for calling external MCP servers |
Transports
Stdio (default)
For CLI-based clients such as Claude Desktop and VS Code. Reads JSON-RPC from stdin, writes to stdout; all logging goes to stderr per the MCP spec.
log.Fatal(srv.RunStdio(context.Background()))
// or with OS signal handling:
log.Fatal(srv.RunWithSignal())
HTTP Streamable
Modern HTTP-based transport per MCP 2025-06-18. Supports sessions, SSE streaming for notifications, and standard JSON-RPC over POST.
log.Fatal(srv.RunHTTP(ctx, ":8080"))
// With full options:
import httptransport "github.com/fsvxavier/nexs-fastmcp/pkg/transport/http"
err := srv.RunHTTPWithOptions(ctx, httptransport.Options{
Addr: ":8080",
Path: "/mcp",
AllowedOrigins: []string{"https://myapp.com"},
ShutdownTimeout: 10 * time.Second,
})
SSE (Legacy)
Legacy Server-Sent Events transport for older MCP clients.
log.Fatal(srv.RunSSE(ctx, ":8080"))
Examples
Nine runnable examples are included in the examples/ directory, ordered by complexity:
| Example | Directory | Description |
|---|---|---|
| Hello World | examples/01-hello-world/ | Minimal server with one greeting tool |
| Calculator | examples/02-calculator/ | Math tools with typed struct inputs |
| File Server | examples/03-file-server/ | Static resources and URI templates |
| Prompt Templates | examples/04-prompt-templates/ | Prompt registration with arguments |
| Context & Logging | examples/05-context-logging/ | Session context and structured logging |
| HTTP Transport | examples/06-http-transport/ | HTTP Streamable transport with options |
| Composition | examples/07-composition/ | Combining tools, resources, and prompts |
| Client | examples/08-client/ | Using the built-in MCP client |
| Lifespan | examples/09-lifespan/ | Lifecycle hooks and shared state |
Run any example:
cd examples/01-hello-world
go run .
Send a JSON-RPC message over stdio:
echo '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{
"protocolVersion":"2025-06-18",
"capabilities":{},
"clientInfo":{"name":"test","version":"0.1"}
}}' | go run examples/01-hello-world/main.go
Documentation
Full documentation is in the docs/ directory:
| Document | Description |
|---|---|
| Getting Started | Installation, first server, running with Claude Desktop |
| Tools | Registering tools, input schemas, handlers, annotations |
| Resources | Static resources, URI templates, MIME types |
| Prompts | Prompt registration, rendering, arguments |
| Transports | Stdio, HTTP Streamable, SSE β configuration and usage |
| Lifespan | Server lifecycle, shared state, teardown |
| Context | Context helpers β session, logging, lifespan access |
| Client | MCP client for calling servers programmatically |
| Schema | JSON Schema generation and validation |
| Observability | Logging, Prometheus metrics, OpenTelemetry tracing, health checks |
| Registry | Component registry, duplicate policies, filtering |
| Protocol | Wire types, error codes, content constructors |
| Examples | Walkthrough of all 9 example projects |
| API Reference | Complete public API surface listing |
Dependencies
| Dependency | Purpose |
|---|---|
gofiber/fiber/v3 | HTTP transport layer |
google/uuid | Session ID generation |
invopop/jsonschema | JSON Schema generation from Go types |
prometheus/client_golang | Prometheus metrics |
santhosh-tekuri/jsonschema/v6 | JSON Schema validation |
go.opentelemetry.io/otel | OpenTelemetry tracing |
go.uber.org/zap | Structured logging |
Contributing
Contributions are welcome. Please follow standard Go conventions:
# Format and vet
go fmt ./...
go vet ./...
# Run tests
go test ./...
# Run tests with race detection
go test -race ./...
License
Copyright Β© Your Name. Licensed under the Apache 2.0 License.
