Skip to content

Commit 3d1af19

Browse files
findleyrfindleyr
committed
docs: add feature and troubleshooting documentation
WIP: filling out the structure DO NOT REVIEW DO NOT SUBMIT
1 parent c2c810b commit 3d1af19

File tree

13 files changed

+202
-9
lines changed

13 files changed

+202
-9
lines changed

‎.github/workflows/readme-check.yml‎

Lines changed: 11 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -1,11 +1,13 @@
11
name: README Check
22
on:
3-
workflow_dispatch:
3+
workflow_dispatch:
44
pull_request:
55
paths:
66
- 'internal/readme/**'
77
- 'README.md'
8-
8+
- 'internal/docs/**'
9+
- 'docs/**'
10+
911
permissions:
1012
contents: read
1113

@@ -17,15 +19,15 @@ jobs:
1719
uses: actions/setup-go@v5
1820
- name: Check out code
1921
uses: actions/checkout@v4
20-
- name: Check README is up-to-date
22+
- name: Check docs is up-to-date
2123
run: |
22-
go generate ./internal/readme
24+
go generate ./...
2325
if [ -n "$(git status --porcelain)" ]; then
24-
echo "ERROR: README.md is not up-to-date!"
26+
echo "ERROR: docs are not up-to-date!"
2527
echo ""
26-
echo "The README.md file differs from what would be generated by `go generate ./internal/readme`."
27-
echo "Please update internal/readme/README.src.md instead of README.md directly,"
28-
echo "then run `go generate ./internal/readme` to regenerate README.md."
28+
echo "The docs differ from what would be generated by `go generate ./...`."
29+
echo "Please update internal/**/*.src.md instead of directly editing README.md or docs/ files,"
30+
echo "then run `go generate ./...` to regenerate docs."
2931
echo ""
3032
echo "Changes:"
3133
git status --porcelain
@@ -34,4 +36,4 @@ jobs:
3436
git diff
3537
exit 1
3638
fi
37-
echo "README.md is up-to-date"
39+
echo "Docs are up-to-date."

‎docs/README.md‎

Lines changed: 40 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,40 @@
1+
<!-- Autogenerated by weave; DO NOT EDIT -->
2+
These docs are a work-in-progress.
3+
4+
# Features
5+
6+
This doc mirrors the official MCP spec hosted at
7+
https://modelcontextprotocol.io/specification/2025-06-18
8+
9+
## Base Protocol
10+
11+
1. [Lifecycle (Clients, Servers, and Sessions)](protocol.md#lifecycle).
12+
1. [Transports](protocol.md#transports)
13+
1. [Streamable transport](protocol.md#streamable-transport)
14+
1. [Stateless mode](protocol.md#stateless-mode)
15+
1. [Authorization](protocol.md#authorization)
16+
1. [Security](protocol.md#security)
17+
1. [Utilities](protocol.md#utilities)
18+
1. [Cancellation](utilities.md#cancellation)
19+
1. [Ping](utilities.md#ping)
20+
1. [Progress](utilities.md#progress)
21+
22+
## Client Features
23+
24+
1. [Roots](client.md#roots)
25+
1. [Sampling](client.md#sampling)
26+
1. [Elicitation](clients.md#elicitation)
27+
28+
## Server Features
29+
30+
1. [Prompts](server.md#prompts)
31+
1. [Resources](server.md#resources)
32+
1. [Tools](tools.md)
33+
1. [Utilities](server.md#utilities)
34+
1. [Completion](server.md#completion)
35+
1. [Logging](server.md#logging)
36+
1. [Pagination](server.md#pagination)
37+
38+
# TroubleShooting
39+
40+
See [troubleshooting.md](troubleshooting.md) for a troubleshooting guide.

‎docs/client.md‎

Lines changed: 8 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,8 @@
1+
<!-- Autogenerated by weave; DO NOT EDIT -->
2+
# Support for MCP Client Features
3+
4+
## Roots
5+
6+
## Sampling
7+
8+
## Elicitation

‎docs/protocol.md‎

Lines changed: 22 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,22 @@
1+
<!-- Autogenerated by weave; DO NOT EDIT -->
2+
# Support for the MCP Base protocol
3+
4+
## Lifecycle
5+
6+
## Transports
7+
8+
### Streamable Transport
9+
10+
### Stateless Mode
11+
12+
## Authorization
13+
14+
## Security
15+
16+
## Utilities
17+
18+
### Cancellation
19+
20+
### Ping
21+
22+
### Progress

‎docs/server.md‎

Lines changed: 18 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,18 @@
1+
<!-- Autogenerated by weave; DO NOT EDIT -->
2+
# Support for MCP server features
3+
4+
## Prompts
5+
6+
## Resources
7+
8+
## Tools
9+
10+
Tools are a big topic! See [tools.md](tools.md) for details.
11+
12+
## Utilities
13+
14+
### Completion
15+
16+
### Logging
17+
18+
### Pagination

‎docs/tools.md‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,2 @@
1+
<!-- Autogenerated by weave; DO NOT EDIT -->
2+
# Troubleshooting

‎internal/docs/README.src.md‎

Lines changed: 39 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,39 @@
1+
These docs are a work-in-progress.
2+
3+
# Features
4+
5+
This doc mirrors the official MCP spec hosted at
6+
https://modelcontextprotocol.io/specification/2025-06-18
7+
8+
## Base Protocol
9+
10+
1. [Lifecycle (Clients, Servers, and Sessions)](protocol.md#lifecycle).
11+
1. [Transports](protocol.md#transports)
12+
1. [Streamable transport](protocol.md#streamable-transport)
13+
1. [Stateless mode](protocol.md#stateless-mode)
14+
1. [Authorization](protocol.md#authorization)
15+
1. [Security](protocol.md#security)
16+
1. [Utilities](protocol.md#utilities)
17+
1. [Cancellation](utilities.md#cancellation)
18+
1. [Ping](utilities.md#ping)
19+
1. [Progress](utilities.md#progress)
20+
21+
## Client Features
22+
23+
1. [Roots](client.md#roots)
24+
1. [Sampling](client.md#sampling)
25+
1. [Elicitation](clients.md#elicitation)
26+
27+
## Server Features
28+
29+
1. [Prompts](server.md#prompts)
30+
1. [Resources](server.md#resources)
31+
1. [Tools](tools.md)
32+
1. [Utilities](server.md#utilities)
33+
1. [Completion](server.md#completion)
34+
1. [Logging](server.md#logging)
35+
1. [Pagination](server.md#pagination)
36+
37+
# TroubleShooting
38+
39+
See [troubleshooting.md](troubleshooting.md) for a troubleshooting guide.

‎internal/docs/client.src.md‎

Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,7 @@
1+
# Support for MCP Client Features
2+
3+
## Roots
4+
5+
## Sampling
6+
7+
## Elicitation

‎internal/docs/doc.go‎

Lines changed: 13 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,13 @@
1+
// Copyright 2025 The Go MCP SDK Authors. All rights reserved.
2+
// Use of this source code is governed by an MIT-style
3+
// license that can be found in the LICENSE file.
4+
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/client.md ./client.src.md
7+
//go:generate go run golang.org/x/example/internal/cmd/weave@latest -o ../../docs/protocol.md ./protocol.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/tools.md ./tools.src.md
10+
//go:generate go run golang.org/x/example/internal/cmd/weave@latest -o ../../docs/tools.md ./troubleshooting.src.md
11+
12+
// The doc package generates the documentation at /doc, via go:generate.
13+
package doc

‎internal/docs/protocol.src.md‎

Lines changed: 23 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,23 @@
1+
# Support for the MCP Base protocol
2+
3+
%toc
4+
5+
## Lifecycle
6+
7+
## Transports
8+
9+
### Streamable Transport
10+
11+
### Stateless Mode
12+
13+
## Authorization
14+
15+
## Security
16+
17+
## Utilities
18+
19+
### Cancellation
20+
21+
### Ping
22+
23+
### Progress

0 commit comments

Comments
 (0)