modelcontextprotocol/go-sdk
Watch
1
0
Fork
You've already forked go-sdk
 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions 2
766 commits 1 branch 33 tags 5.3 MiB
Commit graph go-sdk/internal/docs/server.src.md
Author SHA1 Message Date
Guglielmo Colombo
b8c53fedd6
 		mcp: add docs for tier 1 assessment (#1195) 
Closes open points in
[comment](https://github.com/modelcontextprotocol/modelcontextprotocol/issues/3220#issuecomment-5373089321)
 2026-08-24 12:00:59 +02:00
Guglielmo Colombo
fa548d7401
 		docs: update docs (#1089) 2026-07-16 11:11:22 +02:00
Guglielmo Colombo
22d4988a16
 		mcp: update docs references (#1023) 
Update docs
 2026-06-24 12:39:39 +00:00
Guglielmo Colombo
b9e6fc5a66
 		mcp: add documentation for new protocol version (#1019) 
Add documentation for new protocol version in the `internal/docs`
 2026-06-23 17:07:38 +02:00
Guglielmo Colombo
b6649db4f9
 		mcp: Deprecate roots, sampling and logging (SEP-2577) (#1017) 
Fixes #1013
 2026-06-23 11:11:08 +02:00
Guglielmo Colombo
79e1a13dcf
 		mcp: tool.InputSchema and tool.OutputSchema validation (SEP-2106) (#1009) 
Fixes #990
 2026-06-16 13:55:47 +02:00
Dinesh
1209861858
 		Add documentation backed by mkdocs (#883) 
Affects /docs - (Refined Documentation for deployment and added Some
Supporting documentation)
Added a github action for deployment

Fixes #835  

Added Support for mkdocs
Example -  https://dinesht04.github.io/go-sdk/

Requires Configuration of Github pages as follows:-

1. Enable Github Pages
2. Select gh-pages branch for deployment

<img width="1237" height="817" alt="gh-pages"
src="https://github.com/user-attachments/assets/01f0b012-d5f3-4011-9af9-7269e657ae6a"
/>

## Sources
# For mkdocs.yaml
1.
https://github.com/modelcontextprotocol/python-sdk/blob/main/mkdocs.yml
2. https://github.com/modelcontextprotocol/java-sdk/blob/main/mkdocs.yml
  3. MKDocs official documentation
# For Github Action
1.
https://github.com/modelcontextprotocol/python-sdk/blob/main/.github/workflows/publish-docs-manually.yml
2.
https://github.com/modelcontextprotocol/java-sdk/blob/main/.github/workflows/docs.yml
3.
https://github.com/james-willett/material-mkdocs-youtube-2024/blob/main/.github/workflows/ci.yml
- From Youtube Tutorial
 2026-04-09 14:25:43 +02:00
Sam Morrow
c2c7edc3f0
 		perf: add schema caching to avoid repeated reflection (#685) 
## Summary

This PR adds schema caching that dramatically reduces the cost of tool
registration in stateless server patterns.

**Contributors:** Thanks to @omgitsads and @almaleksia for collaborating
on and researching this solution!

## Problem

In stateless deployments like `github/github-mcp-server`, a new
`*mcp.Server` is created for each incoming request. This means `AddTool`
is called repeatedly for the same tools, causing:

1. **For typed handlers**: `jsonschema.ForType()` reflection is called
every time
2. **For pre-defined schemas**: `schema.Resolve()` is called every time

## Solution

Add a `schemaCache` that stores:
- Schemas by `reflect.Type` (for auto-generated schemas from typed
handlers)
- Resolved schemas by schema pointer (for pre-defined schemas)

The cache is:
- Concurrent-safe using `sync.Map`
- Unbounded (typical MCP servers have &lt;100 tools)
- Global (lives across server instances)

## Benchmark Results

```
BenchmarkAddToolTypedHandler-22          977080    1223 ns/op     1208 B/op    21 allocs/op
BenchmarkAddToolTypedHandlerNoCache-22    6764  161463 ns/op    39262 B/op  1072 allocs/op
```

| Metric | With Cache | Without Cache | Improvement |
|--------|------------|---------------|-------------|
| Time | 1,223 ns/op | 161,463 ns/op | **132x faster** |
| Allocations | 21 allocs | 1,072 allocs | **51x fewer** |
| Memory | 1,208 B/op | 39,262 B/op | **32x less** |

## Files Changed

- `mcp/schema_cache.go` - New cache implementation
- `mcp/server.go` - Modified `setSchema` to use cache
- `mcp/schema_cache_test.go` - Unit tests for caching behavior
- `mcp/schema_cache_benchmark_test.go` - Benchmarks

## Impact for Integrators

**Automatic** - no code changes required. Integrators using:
- Typed handlers (`AddTool[In, Out]`) → cache by type
- Pre-defined schemas (`Tool{InputSchema: schema}`) → cache by pointer

Both patterns benefit from caching after the first call.

---

## Real-World Performance Validation

The following benchmarks were conducted using `github/github-mcp-server`
(a production MCP server with ~130 tools) to validate the performance
impact in a real-world scenario.

### Test Environment
- **Server:** github-mcp-server (stateless HTTP deployment)
- **Tools registered per request:** ~130 tools
- **Test methodology:** Python benchmark client, 30 iterations
(latency), 100 iterations (stress)
- **Date:** December 4, 2025

### Configurations Tested

| Configuration | Description |
|--------------|-------------|
| **main (mcp-go)** | Original implementation using mcp-go library |
| **go-sdk (no cache)** | go-sdk WITHOUT schema caching (broken) |
| **go-sdk (with cache)** | go-sdk WITH this PR&#39;s schema caching fix
|

### Latency Test Results (n=30)

#### Operation: `initialize`

| Configuration | P50 | P99 | Status |
|--------------|-----|-----|--------|
| main (mcp-go) | 11.48ms | 14.00ms | ✅ Baseline |
| go-sdk (no cache) | 20.47ms | 25.30ms | 🔴 **+78% REGRESSION** |
| go-sdk (with cache) | 10.36ms | 14.33ms | ✅ **FIXED (-10%)** |

#### Operation: `tools/list`

| Configuration | P50 | P99 | Status |
|--------------|-----|-----|--------|
| main (mcp-go) | 13.46ms | 22.47ms | ✅ Baseline |
| go-sdk (no cache) | 22.98ms | 29.11ms | 🔴 **+71% REGRESSION** |
| go-sdk (with cache) | 14.15ms | 15.91ms | ✅ **FIXED (+5%)** |

#### Operation: `prompts/list`

| Configuration | P50 | P99 | Status |
|--------------|-----|-----|--------|
| main (mcp-go) | 11.56ms | 13.81ms | ✅ Baseline |
| go-sdk (no cache) | 21.00ms | 26.42ms | 🔴 **+82% REGRESSION** |
| go-sdk (with cache) | 10.77ms | 15.25ms | ✅ **FIXED (-7%)** |

### Stress Test Results (n=100)

| Configuration | P50 (initialize) | P50 (tools/list) | P50
(prompts/list) |

|--------------|------------------|------------------|-------------------|
| main (mcp-go) | 12.06ms | 14.30ms | 11.34ms |
| go-sdk (no cache) | 20.06ms | 23.44ms | 19.59ms |
| go-sdk (with cache) | **11.83ms** | **14.58ms** | **11.05ms** |

### Memory/Allocation Comparison (from pprof)

| Configuration | Total Allocations | Comparison |
|--------------|-------------------|------------|
| main (mcp-go) | 355.91 MB | Baseline |
| go-sdk (no cache) | **1208.70 MB** | 🔴 **3.4x MORE allocations** |

#### Top Allocation Sources - go-sdk WITHOUT cache (broken)

| Function | Size | % | Issue |
|----------|------|---|-------|
| `jsonschema.UnmarshalJSON` | 324.60 MB | 27% | 🚨 Schema re-parsing |
| `encoding/json.Unmarshal` | 341.10 MB | 28% | JSON deserialization |
| `jsonschema.resolve` | 219.51 MB | 18% | 🚨 Schema re-resolution |
| `jsonschema.MarshalJSON` | 92.52 MB | 8% | Schema JSON encoding |

### Root Cause Analysis

The `google/jsonschema-go` library regenerates JSON schemas on every
request instead of caching them. In a server with ~130 tools, this
causes:
- **70-80% latency regression** on all MCP operations
- **3.4x more memory allocations** per request
- **~70% of all allocations** are schema-related operations

### Key Findings

1. ✅ **REGRESSION CONFIRMED:** go-sdk without schema caching is 70-80%
slower than mcp-go
2. ✅ **FIX VERIFIED:** Schema caching restores performance to baseline
(or better)
3. ✅ **MEMORY IMPACT:** 3.4x reduction in allocations with caching
4. ✅ **PRODUCTION READY:** Fixed version performs equivalently to mcp-go
baseline

---------

Co-authored-by: Adam Holt <4619+omgitsads@users.noreply.github.com>
Co-authored-by: Ksenia Bobrova <1885174+almaleksia@users.noreply.github.com>
 2026-01-20 20:16:46 -05:00
Robert Findley
3430e2242e
 		mcp: add Capabilities fields to ServerOptions and ClientOptions (#713) 
This allows users to configure default capabilities, disable defaults,
or suppress listChanged notifications by setting ListChanged: false.

Key changes:
- Add ServerOptions.Capabilities and ClientOptions.Capabilities fields.
- Merge user-provided capabilities with dynamically-added ones (tools,
  prompts, resources, sampling, elicitation).
- Check ListChanged before sending list-changed notifications.
- Deprecate HasPrompts, HasResources, HasTools on ServerOptions.
- Remove unreleased ElicitationModes field from ClientOptions.
- Add clone methods to capability structs using shallowClone helper.
- Add synctest-based tests for notification behavior (go1.25).
- Add TestClientCapabilitiesOverWire and TestServerCapabilitiesOverWire
- Document the new Capabilities API in docs/

Updates #706
 2025-12-11 20:17:46 -05:00
Jonathan Amsterdam
4e9a387d04
 		doc: document logging (#497) 
For #442.
 2025-09-19 11:58:58 -04:00
Jonathan Amsterdam
4fa725857c
 		docs: document resources (#505) 2025-09-19 11:46:50 -04:00
Robert Findley
5985a7cbba
 		docs: document tool support (#498) 
Document tool support, and tweak the wording for prompts.

For #442
 2025-09-19 10:48:59 -04:00
Robert Findley
28753c9f12
 		docs: document completion support (#495) 2025-09-18 14:27:35 -04:00
Robert Findley
49d45a8097
 		docs: document pagination (#491) 
For #442
 2025-09-18 13:31:54 -04:00
Jonathan Amsterdam
fed5106631
 		mcp: add prompt feature doc (#487) 2025-09-18 12:27:02 -04:00
Robert Findley
ac2f175214
 		docs: add feature and troubleshooting documentation (#463) 
Add a framework for feature documentation, and start populating it with
our SDK documentation.

This framework is as follows:
- internal/docs/**.src.md is the markdown source for the docs/
  directory.
- The x/example/internal/cmd/weave tool is used to compile these docs to
  the top-level docs, supporting both linked code samples and generated
  tables of contents.
- The readme-check workflow is updated to check these docs as well.
- The structure of these docs follows the MCP spec.
- Wherever possible, example code is linked from actual Go documentation
  examples, so that it is testable.

Some minor modifications to the weave tool were made to support this
framework.

Additionally, partially fill out this documentation with content on
base protocol and client features, as well as troubleshooting help.

Along the way, a bug was encountered that our LoggingTransport was not
concurrency safe. This is fixed with a mutex.

Fixes https://github.com/modelcontextprotocol/go-sdk/issues/466
Fixes https://github.com/modelcontextprotocol/go-sdk/issues/409
Updates https://github.com/modelcontextprotocol/go-sdk/issues/442
 2025-09-16 11:13:40 -04:00