Skip to content

Commit 793be74

Browse files
findleyrfindleyr
committed
document stdio transport
1 parent 9ce3b34 commit 793be74

File tree

6 files changed

+70
-21
lines changed

6 files changed

+70
-21
lines changed

‎docs/protocol.md‎

Lines changed: 30 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -3,9 +3,16 @@
33

44
1. [Lifecycle](#lifecycle)
55
1. [Transports](#transports)
6+
1. [Stdio Transport](#stdio-transport)
7+
1. [Streamable Transport](#streamable-transport)
8+
1. [Custom transports](#custom-transports)
9+
1. [Concurrency](#concurrency)
610
1. [Authorization](#authorization)
711
1. [Security](#security)
812
1. [Utilities](#utilities)
13+
1. [Cancellation](#cancellation)
14+
1. [Ping](#ping)
15+
1. [Progress](#progress)
916

1017
## Lifecycle
1118

@@ -87,22 +94,37 @@ func Example_lifeCycle() {
8794
## Transports
8895

8996
A
97+
[transport](https://modelcontextprotocol.io/specification/2025-06-18/basic/transports)
98+
can be used to send JSON-RPC messages from client to server, or vice-versa.
99+
100+
In the SDK, this is achieved by implementing the
90101
[`Transport`](https://pkg.go.dev/github.com/modelcontextprotocol/go-sdk/mcp#Transport)
91-
is used to connect a client or server to a peer. Specifically, it's something
92-
that can create a (logical) bidirectional stream of JSON-RPC messages. Most
93-
transport implementations described below are specific to either the client or
94-
server: a "client transport" is something that can be used to connect a client
95-
to a server, and a "server transport" is something that can be used to connect
96-
a server to a client. However, it's possible for a transport to be both a
97-
client and server transport, such as the `InMemoryTransport` used in the
102+
interface, which creates a (logical) bidirectional stream of JSON-RPC messages.
103+
Most transport implementations described below are specific to either the
104+
client or server: a "client transport" is something that can be used to connect
105+
a client to a server, and a "server transport" is something that can be used to
106+
connect a server to a client. However, it's possible for a transport to be both
107+
a client and server transport, such as the `InMemoryTransport` used in the
98108
lifecycle example above.
99109

100110
Transports should not be reused for multiple connections: if you need to create
101111
multiple connections, use different transports.
102112

103113
### Stdio Transport
104114

105-
<!-- TODO -->
115+
In the
116+
[`stdio`](https://modelcontextprotocol.io/specification/2025-06-18/basic/transports#stdio)
117+
transport clients communicate with an MCP server running in a subprocess using
118+
newline-delimited JSON over its stdin/stdout.
119+
120+
**Client-side**: the client side of the `stdio` transport is implemented by
121+
[`CommandTransport`](https://pkg.go.dev/github.com/modelcontextprotocol/go-sdk/mcp#CommandTransport),
122+
which starts the a given `exec.Cmd` as a subprocess and communicates over its
123+
stdin/stdout.
124+
125+
**Server-side**: the server side of the `stdio` transport is implemented by
126+
`StdioTransport`, which connects over the current processes `os.Stdin` and
127+
`os.Stdout`.
106128

107129
### Streamable Transport
108130

‎docs/server.md‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -5,6 +5,9 @@
55
1. [Resources](#resources)
66
1. [Tools](#tools)
77
1. [Utilities](#utilities)
8+
1. [Completion](#completion)
9+
1. [Logging](#logging)
10+
1. [Pagination](#pagination)
811

912
## Prompts
1013

‎go.mod‎

Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -8,3 +8,10 @@ require (
88
github.com/yosida95/uritemplate/v3 v3.0.2
99
golang.org/x/tools v0.34.0
1010
)
11+
12+
require golang.org/x/example v0.0.0-20250915201037-7f05d217867b // indirect
13+
14+
tool (
15+
golang.org/x/example
16+
golang.org/x/example/internal/cmd/weave
17+
)

‎go.sum‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -6,5 +6,7 @@ github.com/google/jsonschema-go v0.2.3 h1:dkP3B96OtZKKFvdrUSaDkL+YDx8Uw9uC4Y+euk
66
github.com/google/jsonschema-go v0.2.3/go.mod h1:r5quNTdLOYEz95Ru18zA0ydNbBuYoo9tgaYcxEYhJVE=
77
github.com/yosida95/uritemplate/v3 v3.0.2 h1:Ed3Oyj9yrmi9087+NczuL5BwkIc4wvTb5zIM+UJPGz4=
88
github.com/yosida95/uritemplate/v3 v3.0.2/go.mod h1:ILOh0sOhIJR3+L/8afwt/kE++YT040gmv5BQTMR2HP4=
9+
golang.org/x/example v0.0.0-20250915201037-7f05d217867b h1:Wr+2JgQ9/QlJUpu1AIgkS/fEZBFwK9j6JpaGZF4sF9s=
10+
golang.org/x/example v0.0.0-20250915201037-7f05d217867b/go.mod h1:9O/DkmvHFcqWXVELN11KJWAhgsAn6PEWo5RshNTuHQY=
911
golang.org/x/tools v0.34.0 h1:qIpSLOxeCYGg9TrcJokLBG4KFA6d795g0xkBkiESGlo=
1012
golang.org/x/tools v0.34.0/go.mod h1:pAP9OwEaY1CAW3HOmg3hLZC5Z0CCmzjAF2UQMSqNARg=

‎internal/docs/doc.go‎

Lines changed: 5 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -2,11 +2,11 @@
22
// Use of this source code is governed by an MIT-style
33
// license that can be found in the LICENSE file.
44

5-
//go:generate go run golang.org/x/example/internal/cmd/weave@latest -o ../../docs/README.md ./README.src.md
6-
//go:generate go run golang.org/x/example/internal/cmd/weave@latest -o ../../docs/protocol.md ./protocol.src.md
7-
//go:generate go run golang.org/x/example/internal/cmd/weave@latest -o ../../docs/client.md ./client.src.md
8-
//go:generate go run golang.org/x/example/internal/cmd/weave@latest -o ../../docs/server.md ./server.src.md
9-
//go:generate go run golang.org/x/example/internal/cmd/weave@latest -o ../../docs/troubleshooting.md ./troubleshooting.src.md
5+
//go:generate go tool weave -o ../../docs/README.md ./README.src.md
6+
//go:generate go tool weave -o ../../docs/protocol.md ./protocol.src.md
7+
//go:generate go tool weave -o ../../docs/client.md ./client.src.md
8+
//go:generate go tool weave -o ../../docs/server.md ./server.src.md
9+
//go:generate go tool weave -o ../../docs/troubleshooting.md ./troubleshooting.src.md
1010

1111
// The doc package generates the documentation at /doc, via go:generate.
1212
//

‎internal/docs/protocol.src.md‎

Lines changed: 23 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -45,22 +45,37 @@ it is the client's responsibility to end the session.
4545
## Transports
4646

4747
A
48+
[transport](https://modelcontextprotocol.io/specification/2025-06-18/basic/transports)
49+
can be used to send JSON-RPC messages from client to server, or vice-versa.
50+
51+
In the SDK, this is achieved by implementing the
4852
[`Transport`](https://pkg.go.dev/github.com/modelcontextprotocol/go-sdk/mcp#Transport)
49-
is used to connect a client or server to a peer. Specifically, it's something
50-
that can create a (logical) bidirectional stream of JSON-RPC messages. Most
51-
transport implementations described below are specific to either the client or
52-
server: a "client transport" is something that can be used to connect a client
53-
to a server, and a "server transport" is something that can be used to connect
54-
a server to a client. However, it's possible for a transport to be both a
55-
client and server transport, such as the `InMemoryTransport` used in the
53+
interface, which creates a (logical) bidirectional stream of JSON-RPC messages.
54+
Most transport implementations described below are specific to either the
55+
client or server: a "client transport" is something that can be used to connect
56+
a client to a server, and a "server transport" is something that can be used to
57+
connect a server to a client. However, it's possible for a transport to be both
58+
a client and server transport, such as the `InMemoryTransport` used in the
5659
lifecycle example above.
5760

5861
Transports should not be reused for multiple connections: if you need to create
5962
multiple connections, use different transports.
6063

6164
### Stdio Transport
6265

63-
<!-- TODO -->
66+
In the
67+
[`stdio`](https://modelcontextprotocol.io/specification/2025-06-18/basic/transports#stdio)
68+
transport clients communicate with an MCP server running in a subprocess using
69+
newline-delimited JSON over its stdin/stdout.
70+
71+
**Client-side**: the client side of the `stdio` transport is implemented by
72+
[`CommandTransport`](https://pkg.go.dev/github.com/modelcontextprotocol/go-sdk/mcp#CommandTransport),
73+
which starts the a given `exec.Cmd` as a subprocess and communicates over its
74+
stdin/stdout.
75+
76+
**Server-side**: the server side of the `stdio` transport is implemented by
77+
`StdioTransport`, which connects over the current processes `os.Stdin` and
78+
`os.Stdout`.
6479

6580
### Streamable Transport
6681

0 commit comments

Comments
 (0)