Skip to content

Commit 1819394

Browse files
cubahnocubahno
committed
Add MCP server generation
1 parent e70690d commit 1819394

31 files changed

Lines changed: 1921 additions & 36 deletions

‎AGENTS.md‎

Lines changed: 20 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -238,3 +238,23 @@ make lint # Check for lint issues
238238
```
239239

240240
**Important**: Do NOT run `make generate` when adding a new framework - only regenerate the specific examples you're working on.
241+
242+
## Documentation
243+
244+
Documentation is in `docs/` using MkDocs. Key files:
245+
246+
- `docs/mcp-server.md` - MCP server generation guide
247+
- `docs/server-generation.md` - HTTP server generation guide
248+
- `docs/extensions/x-*.md` - Extension documentation
249+
- `mkdocs.yml` - Navigation and config
250+
251+
### Adding documentation
252+
1. Create markdown file in `docs/`
253+
2. Add to `nav:` section in `mkdocs.yml`
254+
3. For extensions, create in `docs/extensions/` and add under Extensions nav
255+
256+
### Local preview
257+
```bash
258+
pip install mkdocs-material
259+
mkdocs serve
260+
```

‎Makefile‎

Lines changed: 19 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -18,6 +18,7 @@ help:
1818
@echo " test: run all tests"
1919
@echo " tidy tidy go mod"
2020
@echo " lint lint the project"
21+
@echo " notice regenerate NOTICE.txt with third-party licenses"
2122

2223
$(GOBIN)/golangci-lint:
2324
curl -sSfL https://raw.githubusercontent.com/golangci/golangci-lint/master/install.sh | sh -s -- -b $(GOBIN) v2.4.0
@@ -106,3 +107,21 @@ docs-install:
106107
@PHONY: docs-serve
107108
docs-serve:
108109
@mkdocs serve
110+
111+
$(GOBIN)/go-licenses:
112+
GOBIN=$(GOBIN) go install github.com/google/go-licenses@latest
113+
114+
.PHONY: notice
115+
notice: $(GOBIN)/go-licenses
116+
@echo "This product includes software developed by DoorDash, Inc." > NOTICE.txt
117+
@echo "Copyright 2025 DoorDash, Inc." >> NOTICE.txt
118+
@echo "" >> NOTICE.txt
119+
@echo "Bundled third-party components and their licenses:" >> NOTICE.txt
120+
@echo "--------------------------------------------------" >> NOTICE.txt
121+
@echo "" >> NOTICE.txt
122+
@$(GOBIN)/go-licenses report ./... 2>/dev/null | sort | awk -F',' 'BEGIN{n=1} {printf "%d) %s\n Source: %s\n License: %s\n\n", n++, $$1, $$2, $$3}' >> NOTICE.txt
123+
@echo "--------------------------------------------------" >> NOTICE.txt
124+
@echo "This NOTICE file must be updated whenever this project adds," >> NOTICE.txt
125+
@echo "vendors, or bundles additional third-party components." >> NOTICE.txt
126+
@echo "" >> NOTICE.txt
127+
@echo "Generated NOTICE.txt"

‎NOTICE.txt‎

Lines changed: 39 additions & 35 deletions
Original file line numberDiff line numberDiff line change
@@ -13,11 +13,11 @@ Bundled third-party components and their licenses:
1313
License: MIT
1414

1515
3) github.com/doordash-oss/oapi-codegen-dd/v3
16-
Source: https://github.com/doordash-oss/oapi-codegen-dd/blob/HEAD/LICENSE.txt
16+
Source: https://github.com/doordash-oss/oapi-codegen-dd/blob/HEAD/v3/LICENSE.txt
1717
License: Apache-2.0
1818

1919
4) github.com/gabriel-vasile/mimetype
20-
Source: https://github.com/gabriel-vasile/mimetype/blob/v1.4.8/LICENSE
20+
Source: https://github.com/gabriel-vasile/mimetype/blob/v1.4.11/LICENSE
2121
License: MIT
2222

2323
5) github.com/go-playground/locales
@@ -29,56 +29,60 @@ Bundled third-party components and their licenses:
2929
License: MIT
3030

3131
7) github.com/go-playground/validator/v10
32-
Source: https://github.com/go-playground/validator/blob/v10.26.0/LICENSE
32+
Source: https://github.com/go-playground/validator/blob/v10.28.0/LICENSE
3333
License: MIT
3434

35-
8) github.com/iancoleman/strcase
35+
8) github.com/google/uuid
36+
Source: https://github.com/google/uuid/blob/v1.6.0/LICENSE
37+
License: BSD-3-Clause
38+
39+
9) github.com/iancoleman/strcase
3640
Source: https://github.com/iancoleman/strcase/blob/v0.3.0/LICENSE
3741
License: MIT
3842

39-
9) github.com/leodido/go-urn
43+
10) github.com/leodido/go-urn
4044
Source: https://github.com/leodido/go-urn/blob/v1.4.0/LICENSE
4145
License: MIT
4246

43-
10) github.com/pb33f/libopenapi
44-
Source: https://github.com/pb33f/libopenapi/blob/v0.25.3/LICENSE
45-
License: MIT
47+
11) github.com/pb33f/jsonpath/pkg/jsonpath
48+
Source: https://github.com/pb33f/jsonpath/blob/v0.7.0/LICENSE
49+
License: Apache-2.0
4650

47-
11) github.com/pb33f/ordered-map/v2
48-
Source: https://github.com/pb33f/ordered-map/blob/v2.2.0/LICENSE
49-
License: Apache-2.0
51+
12) github.com/pb33f/libopenapi
52+
Source: https://github.com/pb33f/libopenapi/blob/v0.31.2/LICENSE
53+
License: MIT
5054

51-
12) github.com/speakeasy-api/jsonpath/pkg/jsonpath
52-
Source: https://github.com/speakeasy-api/jsonpath/blob/v0.6.2/LICENSE
53-
License: Apache-2.0
55+
13) github.com/pb33f/ordered-map/v2
56+
Source: https://github.com/pb33f/ordered-map/blob/v2.3.0/LICENSE
57+
License: Apache-2.0
5458

55-
13) golang.org/x/crypto/sha3
56-
Source: https://cs.opensource.google/go/x/crypto/+/v0.36.0:LICENSE
57-
License: BSD-3-Clause
59+
14) go.yaml.in/yaml/v4
60+
Source: https://github.com/yaml/go-yaml/blob/v4.0.0-rc.3/LICENSE
61+
License: Apache-2.0
5862

59-
14) golang.org/x/mod
60-
Source: https://cs.opensource.google/go/x/mod/+/v0.17.0:LICENSE
61-
License: BSD-3-Clause
63+
15) golang.org/x/crypto/sha3
64+
Source: https://cs.opensource.google/go/x/crypto/+/v0.45.0:LICENSE
65+
License: BSD-3-Clause
6266

63-
15) golang.org/x/net/html
64-
Source: https://cs.opensource.google/go/x/net/+/v0.38.0:LICENSE
65-
License: BSD-3-Clause
67+
16) golang.org/x/mod
68+
Source: https://cs.opensource.google/go/x/mod/+/v0.30.0:LICENSE
69+
License: BSD-3-Clause
6670

67-
16) golang.org/x/sys/cpu
68-
Source: https://cs.opensource.google/go/x/sys/+/v0.31.0:LICENSE
69-
License: BSD-3-Clause
71+
17) golang.org/x/sync
72+
Source: https://cs.opensource.google/go/x/sync/+/v0.19.0:LICENSE
73+
License: BSD-3-Clause
7074

71-
17) golang.org/x/text
72-
Source: https://cs.opensource.google/go/x/text/+/v0.23.0:LICENSE
73-
License: BSD-3-Clause
75+
18) golang.org/x/sys/cpu
76+
Source: https://cs.opensource.google/go/x/sys/+/v0.38.0:LICENSE
77+
License: BSD-3-Clause
7478

75-
18) golang.org/x/tools
76-
Source: https://cs.opensource.google/go/x/tools/+/e35e4ccd:LICENSE
77-
License: BSD-3-Clause
79+
19) golang.org/x/text
80+
Source: https://cs.opensource.google/go/x/text/+/v0.31.0:LICENSE
81+
License: BSD-3-Clause
7882

79-
19) gopkg.in/yaml.v3
80-
Source: https://github.com/go-yaml/yaml/blob/v3.0.1/LICENSE
81-
License: MIT
83+
20) golang.org/x/tools
84+
Source: https://cs.opensource.google/go/x/tools/+/v0.39.0:LICENSE
85+
License: BSD-3-Clause
8286

8387
--------------------------------------------------
8488
This NOTICE file must be updated whenever this project adds,

‎README.md‎

Lines changed: 8 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -28,10 +28,16 @@ on the real value-add for your organization.
2828

2929
### Server Generation
3030
- **Complete server scaffolding** - Generate service interfaces, HTTP adapters, routers, and server main.go
31-
- **12 framework support** - Chi, Echo, Gin, Fiber, std-http, Beego, go-zero, Kratos, GoFrame, Hertz, gorilla-mux, fasthttp
31+
- **13 framework support** - Chi, Echo, Gin, Fiber, std-http, Beego, go-zero, Kratos, GoFrame, Hertz, gorilla-mux, fasthttp, Iris
3232
- **Clean architecture** - Service interface pattern separates business logic from HTTP handling
3333
- **Request/response validation** - Optional validation in generated handlers
3434

35+
### MCP Server Generation
36+
- **[MCP (Model Context Protocol)](https://modelcontextprotocol.io/)** - Generate MCP servers for AI assistant integration
37+
- **Tool generation** - Each API operation becomes an MCP tool that AI assistants can call
38+
- **x-mcp extension** - Control tool names, descriptions, and skip operations
39+
- **Works with Claude Desktop, Cursor, and other MCP clients**
40+
3541
### Configuration & Filtering
3642
- **YAML-based configuration** with JSON schema validation
3743
- **Flexible filtering** - Include/exclude by paths, tags, operation IDs, schema properties, or extensions
@@ -84,6 +90,7 @@ Tested against [2,137 real-world OpenAPI 3.0 specs](https://github.com/cubahno/s
8490
| **Templates** | Monolithic | Composable with `{{define}}` blocks |
8591
| **Programmatic API** | Limited | Full (`ParseContext`, `TypeTracker`) |
8692
| **Server Frameworks** | 7 (Chi, Echo, Fiber, Gin, Gorilla, Iris, std-http) | 13 (+ Beego, go-zero, Kratos, GoFrame, Hertz, fasthttp) |
93+
| **MCP Server** | None | Full (AI assistant integration) |
8794

8895
### Migration
8996

‎configuration-schema.json‎

Lines changed: 16 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -102,6 +102,10 @@
102102
"$ref": "#/definitions/HandlerOptions",
103103
"description": "Handler specifies options for handler/server code generation. If not specified, no handler code is generated."
104104
},
105+
"mcp-server": {
106+
"$ref": "#/definitions/MCPServerOptions",
107+
"description": "MCPServer specifies options for MCP (Model Context Protocol) server generation. If set, generates MCP tools that wrap the generated client for AI assistant integration. Requires client generation to be enabled."
108+
},
105109
"omit-description": {
106110
"type": "boolean",
107111
"description": "OmitDescription specifies whether to omit schema description from the spec in the generated code. Defaults to false."
@@ -310,6 +314,18 @@
310314
"properties": {},
311315
"required": []
312316
},
317+
"MCPServerOptions": {
318+
"type": "object",
319+
"additionalProperties": false,
320+
"description": "Options for MCP (Model Context Protocol) server generation. MCP servers expose API operations as tools that AI assistants (Claude, Cursor, etc.) can invoke.",
321+
"properties": {
322+
"default-skip": {
323+
"type": "boolean",
324+
"description": "If true, skip all operations by default unless x-mcp.skip is explicitly false. If false (default), include all operations unless x-mcp.skip is true."
325+
}
326+
},
327+
"required": []
328+
},
313329
"ServerOptions": {
314330
"type": "object",
315331
"additionalProperties": false,

‎docs/extensions/x-mcp.md‎

Lines changed: 106 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,106 @@
1+
# x-mcp
2+
3+
The `x-mcp` extension controls MCP (Model Context Protocol) tool generation for individual operations.
4+
5+
## Usage
6+
7+
Apply to operations to customize or skip MCP tool generation:
8+
9+
```yaml
10+
paths:
11+
/users:
12+
get:
13+
operationId: listUsers
14+
summary: List all users
15+
x-mcp:
16+
name: "list_users"
17+
description: "Retrieve all users from the system"
18+
19+
/internal/metrics:
20+
get:
21+
operationId: getMetrics
22+
x-mcp:
23+
skip: true
24+
```
25+
26+
## Properties
27+
28+
| Property | Type | Default | Description |
29+
|----------|------|---------|-------------|
30+
| `skip` | boolean | `false` | If `true`, exclude this operation from MCP generation |
31+
| `name` | string | operationId | Override the MCP tool name |
32+
| `description` | string | summary/description | Override the MCP tool description |
33+
34+
## Examples
35+
36+
### Skip an operation
37+
38+
```yaml
39+
/admin/reset:
40+
post:
41+
operationId: resetDatabase
42+
x-mcp:
43+
skip: true # Don't expose to AI assistants
44+
```
45+
46+
### Custom tool name
47+
48+
```yaml
49+
/users:
50+
get:
51+
operationId: listUsers
52+
x-mcp:
53+
name: "get_all_users" # More descriptive for AI
54+
```
55+
56+
### Custom description
57+
58+
```yaml
59+
/users/{id}:
60+
delete:
61+
operationId: deleteUser
62+
x-mcp:
63+
description: "Permanently delete a user. This action cannot be undone."
64+
```
65+
66+
## Interaction with default-skip
67+
68+
The `skip` property interacts with the `default-skip` configuration option:
69+
70+
| `default-skip` | `x-mcp.skip` | Result |
71+
|----------------|--------------|--------|
72+
| `false` (default) | not set | Included |
73+
| `false` | `true` | Skipped |
74+
| `false` | `false` | Included |
75+
| `true` | not set | Skipped |
76+
| `true` | `true` | Skipped |
77+
| `true` | `false` | Included |
78+
79+
Example with `default-skip: true`:
80+
81+
```yaml
82+
# cfg.yaml
83+
generate:
84+
mcp-server:
85+
default-skip: true
86+
87+
# spec.yaml
88+
paths:
89+
/users:
90+
get:
91+
operationId: listUsers
92+
x-mcp:
93+
skip: false # Explicitly include this operation
94+
```
95+
96+
## Notes
97+
98+
- By default, operations without `x-mcp` are included (unless `default-skip: true`)
99+
- The `name` defaults to the `operationId`
100+
- The `description` defaults to the operation's `summary` or `description`
101+
- This extension only affects MCP server generation (`generate.mcp-server`)
102+
103+
## See Also
104+
105+
- [MCP Server Generation](../mcp-server.md)
106+

0 commit comments

Comments
 (0)