autodoc-agent-kit 1.0.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (187) hide show
  1. package/README.md +362 -0
  2. package/package.json +49 -0
  3. package/src/core/module.yaml +5 -0
  4. package/src/modules/design/module.yaml +9 -0
  5. package/src/modules/design/skills/brand-guidelines/LICENSE.txt +202 -0
  6. package/src/modules/design/skills/brand-guidelines/SKILL.md +73 -0
  7. package/src/modules/design/skills/frontend-design/LICENSE.txt +177 -0
  8. package/src/modules/design/skills/frontend-design/SKILL.md +42 -0
  9. package/src/modules/design/skills/web-artifacts-builder/SKILL.md +229 -0
  10. package/src/modules/devops/module.yaml +10 -0
  11. package/src/modules/devops/skills/devops-helper/SKILL.md +60 -0
  12. package/src/modules/devops/skills/k8s-helm/SKILL.md +360 -0
  13. package/src/modules/devops/skills/monitoring-observability/SKILL.md +240 -0
  14. package/src/modules/devops/skills/security-auditor/SKILL.md +105 -0
  15. package/src/modules/engineering/module.yaml +22 -0
  16. package/src/modules/engineering/skills/ai-sdk/SKILL.md +314 -0
  17. package/src/modules/engineering/skills/api-designer/SKILL.md +77 -0
  18. package/src/modules/engineering/skills/code-reviewer/SKILL.md +71 -0
  19. package/src/modules/engineering/skills/db-architect/SKILL.md +50 -0
  20. package/src/modules/engineering/skills/debugger/SKILL.md +59 -0
  21. package/src/modules/engineering/skills/docs-generator/SKILL.md +51 -0
  22. package/src/modules/engineering/skills/git-workflow/SKILL.md +258 -0
  23. package/src/modules/engineering/skills/mcp-builder/LICENSE.txt +202 -0
  24. package/src/modules/engineering/skills/mcp-builder/SKILL.md +236 -0
  25. package/src/modules/engineering/skills/mcp-builder/reference/evaluation.md +602 -0
  26. package/src/modules/engineering/skills/mcp-builder/reference/mcp_best_practices.md +249 -0
  27. package/src/modules/engineering/skills/mcp-builder/reference/node_mcp_server.md +970 -0
  28. package/src/modules/engineering/skills/mcp-builder/reference/python_mcp_server.md +719 -0
  29. package/src/modules/engineering/skills/mcp-builder/scripts/connections.py +151 -0
  30. package/src/modules/engineering/skills/mcp-builder/scripts/evaluation.py +373 -0
  31. package/src/modules/engineering/skills/mcp-builder/scripts/example_evaluation.xml +22 -0
  32. package/src/modules/engineering/skills/mcp-builder/scripts/requirements.txt +2 -0
  33. package/src/modules/engineering/skills/nextjs-15/SKILL.md +312 -0
  34. package/src/modules/engineering/skills/perf-optimizer/SKILL.md +60 -0
  35. package/src/modules/engineering/skills/react-19/SKILL.md +257 -0
  36. package/src/modules/engineering/skills/refactorer/SKILL.md +60 -0
  37. package/src/modules/engineering/skills/skill-authoring-workflow/SKILL.md +183 -0
  38. package/src/modules/engineering/skills/skill-creator/LICENSE.txt +202 -0
  39. package/src/modules/engineering/skills/skill-creator/SKILL.md +356 -0
  40. package/src/modules/engineering/skills/skill-creator/references/output-patterns.md +82 -0
  41. package/src/modules/engineering/skills/skill-creator/references/workflows.md +28 -0
  42. package/src/modules/engineering/skills/skill-creator/scripts/__pycache__/quick_validate.cpython-313.pyc +0 -0
  43. package/src/modules/engineering/skills/skill-creator/scripts/init_skill.py +303 -0
  44. package/src/modules/engineering/skills/skill-creator/scripts/package_skill.py +110 -0
  45. package/src/modules/engineering/skills/skill-creator/scripts/quick_validate.py +95 -0
  46. package/src/modules/engineering/skills/typescript/SKILL.md +231 -0
  47. package/src/modules/engineering/skills/zod-4/SKILL.md +223 -0
  48. package/src/modules/product/module.yaml +51 -0
  49. package/src/modules/product/skills/acquisition-channel-advisor/SKILL.md +643 -0
  50. package/src/modules/product/skills/acquisition-channel-advisor/examples/conversation-flow.md +531 -0
  51. package/src/modules/product/skills/ai-shaped-readiness-advisor/SKILL.md +923 -0
  52. package/src/modules/product/skills/altitude-horizon-framework/SKILL.md +250 -0
  53. package/src/modules/product/skills/altitude-horizon-framework/examples/sample.md +85 -0
  54. package/src/modules/product/skills/business-health-diagnostic/SKILL.md +783 -0
  55. package/src/modules/product/skills/company-research/SKILL.md +385 -0
  56. package/src/modules/product/skills/company-research/examples/sample.md +164 -0
  57. package/src/modules/product/skills/company-research/template.md +60 -0
  58. package/src/modules/product/skills/context-engineering-advisor/SKILL.md +763 -0
  59. package/src/modules/product/skills/customer-journey-map/SKILL.md +346 -0
  60. package/src/modules/product/skills/customer-journey-map/examples/meta-product-manager-skills.md +40 -0
  61. package/src/modules/product/skills/customer-journey-map/examples/sample.md +33 -0
  62. package/src/modules/product/skills/customer-journey-map/template.md +28 -0
  63. package/src/modules/product/skills/customer-journey-mapping-workshop/SKILL.md +523 -0
  64. package/src/modules/product/skills/director-readiness-advisor/SKILL.md +351 -0
  65. package/src/modules/product/skills/director-readiness-advisor/examples/conversation-flow.md +96 -0
  66. package/src/modules/product/skills/discovery-interview-prep/SKILL.md +410 -0
  67. package/src/modules/product/skills/discovery-process/SKILL.md +504 -0
  68. package/src/modules/product/skills/discovery-process/examples/sample.md +60 -0
  69. package/src/modules/product/skills/discovery-process/template.md +39 -0
  70. package/src/modules/product/skills/eol-message/SKILL.md +348 -0
  71. package/src/modules/product/skills/eol-message/examples/sample.md +87 -0
  72. package/src/modules/product/skills/eol-message/template.md +74 -0
  73. package/src/modules/product/skills/epic-breakdown-advisor/SKILL.md +665 -0
  74. package/src/modules/product/skills/epic-hypothesis/SKILL.md +277 -0
  75. package/src/modules/product/skills/epic-hypothesis/examples/sample.md +104 -0
  76. package/src/modules/product/skills/epic-hypothesis/template.md +30 -0
  77. package/src/modules/product/skills/executive-onboarding-playbook/SKILL.md +280 -0
  78. package/src/modules/product/skills/executive-onboarding-playbook/examples/sample.md +116 -0
  79. package/src/modules/product/skills/feature-investment-advisor/SKILL.md +639 -0
  80. package/src/modules/product/skills/feature-investment-advisor/examples/conversation-flow.md +538 -0
  81. package/src/modules/product/skills/finance-based-pricing-advisor/SKILL.md +763 -0
  82. package/src/modules/product/skills/finance-metrics-quickref/SKILL.md +309 -0
  83. package/src/modules/product/skills/jobs-to-be-done/SKILL.md +370 -0
  84. package/src/modules/product/skills/jobs-to-be-done/examples/sample.md +80 -0
  85. package/src/modules/product/skills/jobs-to-be-done/template.md +65 -0
  86. package/src/modules/product/skills/lean-ux-canvas/SKILL.md +561 -0
  87. package/src/modules/product/skills/lean-ux-canvas/examples/sample.md +88 -0
  88. package/src/modules/product/skills/lean-ux-canvas/template.md +32 -0
  89. package/src/modules/product/skills/opportunity-solution-tree/SKILL.md +420 -0
  90. package/src/modules/product/skills/opportunity-solution-tree/examples/sample.md +104 -0
  91. package/src/modules/product/skills/opportunity-solution-tree/template.md +33 -0
  92. package/src/modules/product/skills/pestel-analysis/SKILL.md +376 -0
  93. package/src/modules/product/skills/pestel-analysis/examples/sample.md +143 -0
  94. package/src/modules/product/skills/pestel-analysis/template.md +53 -0
  95. package/src/modules/product/skills/pol-probe/SKILL.md +217 -0
  96. package/src/modules/product/skills/pol-probe/examples/sample.md +136 -0
  97. package/src/modules/product/skills/pol-probe/template.md +59 -0
  98. package/src/modules/product/skills/pol-probe-advisor/SKILL.md +492 -0
  99. package/src/modules/product/skills/positioning-statement/SKILL.md +230 -0
  100. package/src/modules/product/skills/positioning-statement/examples/sample.md +51 -0
  101. package/src/modules/product/skills/positioning-statement/template.md +25 -0
  102. package/src/modules/product/skills/positioning-workshop/SKILL.md +424 -0
  103. package/src/modules/product/skills/prd-development/SKILL.md +655 -0
  104. package/src/modules/product/skills/prd-development/examples/sample.md +43 -0
  105. package/src/modules/product/skills/prd-development/template.md +55 -0
  106. package/src/modules/product/skills/press-release/SKILL.md +269 -0
  107. package/src/modules/product/skills/press-release/examples/sample.md +73 -0
  108. package/src/modules/product/skills/press-release/template.md +39 -0
  109. package/src/modules/product/skills/prioritization-advisor/SKILL.md +448 -0
  110. package/src/modules/product/skills/problem-framing-canvas/SKILL.md +466 -0
  111. package/src/modules/product/skills/problem-framing-canvas/examples/sample.md +58 -0
  112. package/src/modules/product/skills/problem-framing-canvas/template.md +22 -0
  113. package/src/modules/product/skills/problem-statement/SKILL.md +246 -0
  114. package/src/modules/product/skills/problem-statement/examples/sample.md +82 -0
  115. package/src/modules/product/skills/problem-statement/template.md +37 -0
  116. package/src/modules/product/skills/product-strategy-session/SKILL.md +426 -0
  117. package/src/modules/product/skills/product-strategy-session/examples/sample.md +67 -0
  118. package/src/modules/product/skills/product-strategy-session/template.md +38 -0
  119. package/src/modules/product/skills/proto-persona/SKILL.md +326 -0
  120. package/src/modules/product/skills/proto-persona/examples/sample.md +97 -0
  121. package/src/modules/product/skills/proto-persona/template.md +45 -0
  122. package/src/modules/product/skills/recommendation-canvas/SKILL.md +375 -0
  123. package/src/modules/product/skills/recommendation-canvas/examples/sample.md +94 -0
  124. package/src/modules/product/skills/recommendation-canvas/template.md +86 -0
  125. package/src/modules/product/skills/roadmap-planning/SKILL.md +505 -0
  126. package/src/modules/product/skills/roadmap-planning/examples/sample.md +62 -0
  127. package/src/modules/product/skills/roadmap-planning/template.md +30 -0
  128. package/src/modules/product/skills/saas-economics-efficiency-metrics/SKILL.md +694 -0
  129. package/src/modules/product/skills/saas-economics-efficiency-metrics/examples/cash-trap.md +365 -0
  130. package/src/modules/product/skills/saas-economics-efficiency-metrics/examples/healthy-unit-economics.md +279 -0
  131. package/src/modules/product/skills/saas-economics-efficiency-metrics/template.md +263 -0
  132. package/src/modules/product/skills/saas-revenue-growth-metrics/SKILL.md +630 -0
  133. package/src/modules/product/skills/saas-revenue-growth-metrics/examples/healthy-saas.md +131 -0
  134. package/src/modules/product/skills/saas-revenue-growth-metrics/examples/warning-signs.md +229 -0
  135. package/src/modules/product/skills/saas-revenue-growth-metrics/template.md +192 -0
  136. package/src/modules/product/skills/storyboard/SKILL.md +252 -0
  137. package/src/modules/product/skills/storyboard/examples/sample.md +71 -0
  138. package/src/modules/product/skills/storyboard/template.md +41 -0
  139. package/src/modules/product/skills/tam-sam-som-calculator/SKILL.md +392 -0
  140. package/src/modules/product/skills/tam-sam-som-calculator/examples/sample.md +142 -0
  141. package/src/modules/product/skills/tam-sam-som-calculator/scripts/market-sizing.py +95 -0
  142. package/src/modules/product/skills/tam-sam-som-calculator/template.md +35 -0
  143. package/src/modules/product/skills/user-story/SKILL.md +272 -0
  144. package/src/modules/product/skills/user-story/examples/sample.md +110 -0
  145. package/src/modules/product/skills/user-story/scripts/user-story-template.py +65 -0
  146. package/src/modules/product/skills/user-story/template.md +32 -0
  147. package/src/modules/product/skills/user-story-mapping/SKILL.md +285 -0
  148. package/src/modules/product/skills/user-story-mapping/examples/sample.md +77 -0
  149. package/src/modules/product/skills/user-story-mapping/template.md +41 -0
  150. package/src/modules/product/skills/user-story-mapping-workshop/SKILL.md +477 -0
  151. package/src/modules/product/skills/user-story-mapping-workshop/template.md +28 -0
  152. package/src/modules/product/skills/user-story-splitting/SKILL.md +303 -0
  153. package/src/modules/product/skills/user-story-splitting/examples/sample.md +147 -0
  154. package/src/modules/product/skills/user-story-splitting/template.md +37 -0
  155. package/src/modules/product/skills/vp-cpo-readiness-advisor/SKILL.md +409 -0
  156. package/src/modules/product/skills/vp-cpo-readiness-advisor/examples/conversation-flow.md +95 -0
  157. package/src/modules/product/skills/workshop-facilitation/SKILL.md +87 -0
  158. package/src/modules/productivity/module.yaml +9 -0
  159. package/src/modules/productivity/skills/doc-coauthoring/SKILL.md +375 -0
  160. package/src/modules/productivity/skills/internal-comms/LICENSE.txt +202 -0
  161. package/src/modules/productivity/skills/internal-comms/SKILL.md +32 -0
  162. package/src/modules/productivity/skills/internal-comms/examples/3p-updates.md +47 -0
  163. package/src/modules/productivity/skills/internal-comms/examples/company-newsletter.md +65 -0
  164. package/src/modules/productivity/skills/internal-comms/examples/faq-answers.md +30 -0
  165. package/src/modules/productivity/skills/internal-comms/examples/general-comms.md +16 -0
  166. package/src/modules/productivity/skills/technical-writing/SKILL.md +266 -0
  167. package/src/modules/qa/module.yaml +9 -0
  168. package/src/modules/qa/skills/test-strategy/SKILL.md +263 -0
  169. package/src/modules/qa/skills/test-writer/SKILL.md +57 -0
  170. package/src/modules/qa/skills/webapp-testing/LICENSE.txt +202 -0
  171. package/src/modules/qa/skills/webapp-testing/SKILL.md +96 -0
  172. package/src/modules/qa/skills/webapp-testing/examples/console_logging.py +35 -0
  173. package/src/modules/qa/skills/webapp-testing/examples/element_discovery.py +40 -0
  174. package/src/modules/qa/skills/webapp-testing/examples/static_html_automation.py +33 -0
  175. package/src/modules/qa/skills/webapp-testing/scripts/with_server.py +106 -0
  176. package/tools/autodoc-npx-wrapper.js +34 -0
  177. package/tools/cli/autodoc-cli.js +55 -0
  178. package/tools/cli/commands/install.js +36 -0
  179. package/tools/cli/commands/status.js +35 -0
  180. package/tools/cli/commands/uninstall.js +60 -0
  181. package/tools/cli/installers/lib/core/installer.js +164 -0
  182. package/tools/cli/installers/lib/core/manifest.js +49 -0
  183. package/tools/cli/installers/lib/ide/manager.js +112 -0
  184. package/tools/cli/installers/lib/ide/platform-codes.yaml +207 -0
  185. package/tools/cli/installers/lib/modules/manager.js +59 -0
  186. package/tools/cli/lib/ui.js +199 -0
  187. package/tools/cli/lib/welcome.js +82 -0
@@ -0,0 +1,258 @@
1
+ ---
2
+ name: git-workflow
3
+ description: Git branching strategies, conventional commits, PR workflows, and collaboration best practices. Trigger when setting up branching strategies, writing commit messages, creating PRs, or managing Git history.
4
+ ---
5
+
6
+ # Git Workflow Patterns
7
+
8
+ Clean Git history is documentation. Every commit should explain *why* a change was made, not just what.
9
+
10
+ ## Conventional Commits
11
+
12
+ Format: `<type>(<scope>): <description>`
13
+
14
+ ```
15
+ feat(auth): add OAuth2 login with Google
16
+ fix(api): handle null user in session middleware
17
+ refactor(ui): extract Button component from Form
18
+ docs(readme): add setup instructions for Windows
19
+ test(auth): add tests for token refresh flow
20
+ chore(deps): bump axios from 1.6.0 to 1.7.0
21
+ perf(db): add index on users.email column
22
+ ci(github): add deploy workflow for staging
23
+ ```
24
+
25
+ ### Types
26
+
27
+ | Type | Use for |
28
+ |------|---------|
29
+ | `feat` | New feature visible to users |
30
+ | `fix` | Bug fix |
31
+ | `refactor` | Code change with no behavior change |
32
+ | `docs` | Documentation only |
33
+ | `test` | Adding or updating tests |
34
+ | `chore` | Maintenance, dependency updates |
35
+ | `perf` | Performance improvements |
36
+ | `ci` | CI/CD pipeline changes |
37
+ | `build` | Build system, tooling changes |
38
+ | `style` | Formatting (no logic change) |
39
+
40
+ ### Breaking Changes
41
+
42
+ ```
43
+ feat(api)!: change /users endpoint to return paginated response
44
+
45
+ BREAKING CHANGE: The /users endpoint now returns { data, pagination }
46
+ instead of a plain array. Update all consumers.
47
+ ```
48
+
49
+ ## Branching Strategies
50
+
51
+ ### GitHub Flow (Simple Teams)
52
+
53
+ ```
54
+ main ────●────●────●────●──→
55
+ │ ↑ │ ↑
56
+ feature/my-feature ───●────┘ │ │
57
+ fix/bug-123 ────────────●─┘ │
58
+ hotfix/critical ─────────────────●─┘
59
+ ```
60
+
61
+ - `main` is always deployable
62
+ - Feature branches off `main`, PR back to `main`
63
+ - Short-lived branches (days, not weeks)
64
+
65
+ ### Git Flow (Release Cadence)
66
+
67
+ ```
68
+ main ──────────●──────────────●──→ (tagged releases)
69
+ ↑ │ ↑ │
70
+ develop ────●─────┘────●────┘────→
71
+ │ ↑ │
72
+ feature ────●────┘ │
73
+ hotfix ─────────────────●──→ (merges to main + develop)
74
+ ```
75
+
76
+ - `develop` is the integration branch
77
+ - Features branch off `develop`
78
+ - Release branches for stabilization
79
+ - Hotfixes branch off `main`
80
+
81
+ ### Trunk-Based Development (CI/CD Teams)
82
+
83
+ ```
84
+ main ──●──●──●──●──●──●──→ (deployable every commit)
85
+ ```
86
+
87
+ - All developers commit to `main` (or very short-lived branches)
88
+ - Feature flags control incomplete features
89
+ - Requires strong CI/automated tests
90
+
91
+ ## Branch Naming
92
+
93
+ ```bash
94
+ # Pattern: <type>/<ticket>-<short-description>
95
+ feature/PAY-123-stripe-webhooks
96
+ fix/BUG-456-null-session-crash
97
+ hotfix/SEC-789-xss-sanitization
98
+ chore/update-node-18
99
+ experiment/new-cache-strategy
100
+ ```
101
+
102
+ ## PR Best Practices
103
+
104
+ ### PR Title
105
+
106
+ Follow conventional commit format:
107
+ ```
108
+ feat(payments): add Stripe webhook handler for subscription events
109
+ ```
110
+
111
+ ### PR Description Template
112
+
113
+ ```markdown
114
+ ## What
115
+ Brief description of what this PR does.
116
+
117
+ ## Why
118
+ The business/technical reason for this change.
119
+
120
+ ## How
121
+ Key implementation decisions worth reviewing.
122
+
123
+ ## Testing
124
+ - [ ] Unit tests added/updated
125
+ - [ ] Manual testing steps
126
+
127
+ ## Breaking Changes
128
+ None / Description of breaking change
129
+ ```
130
+
131
+ ### PR Size
132
+
133
+ - **Ideal**: <400 lines changed
134
+ - **Acceptable**: 400-800 lines
135
+ - **Requires justification**: >800 lines
136
+
137
+ Split large PRs by: feature slice, refactor+feature, or infrastructure+logic.
138
+
139
+ ## Common Git Operations
140
+
141
+ ### Interactive Rebase (Cleanup Before PR)
142
+
143
+ ```bash
144
+ # Squash last 3 commits
145
+ git rebase -i HEAD~3
146
+
147
+ # Options in interactive editor:
148
+ # pick = keep as-is
149
+ # squash = merge into previous commit
150
+ # reword = change commit message
151
+ # drop = remove commit
152
+ ```
153
+
154
+ ### Stashing
155
+
156
+ ```bash
157
+ git stash push -m "WIP: half-done feature" # stash with name
158
+ git stash list # show all stashes
159
+ git stash pop # apply and remove last stash
160
+ git stash apply stash@{2} # apply specific stash
161
+ ```
162
+
163
+ ### Undoing Changes
164
+
165
+ ```bash
166
+ # Undo last commit, keep changes staged
167
+ git reset --soft HEAD~1
168
+
169
+ # Undo last commit, keep changes unstaged
170
+ git reset --mixed HEAD~1 # (this is the default)
171
+
172
+ # Discard all local changes (DESTRUCTIVE)
173
+ git restore .
174
+
175
+ # Revert a published commit (safe for shared branches)
176
+ git revert <commit-hash>
177
+
178
+ # Fix the last commit message (only before push)
179
+ git commit --amend -m "corrected message"
180
+ ```
181
+
182
+ ### Syncing with Remote
183
+
184
+ ```bash
185
+ # Fetch without merging
186
+ git fetch origin
187
+
188
+ # Rebase feature branch onto updated main (preferred over merge)
189
+ git fetch origin
190
+ git rebase origin/main
191
+
192
+ # If rebase conflicts:
193
+ git status # see conflicted files
194
+ # fix conflicts
195
+ git add <file>
196
+ git rebase --continue
197
+ # or abort
198
+ git rebase --abort
199
+ ```
200
+
201
+ ### Cherry Pick
202
+
203
+ ```bash
204
+ # Apply a single commit from another branch
205
+ git cherry-pick <commit-hash>
206
+
207
+ # Cherry pick a range
208
+ git cherry-pick A^..B
209
+ ```
210
+
211
+ ## Git Hooks
212
+
213
+ ### pre-commit (`.husky/pre-commit`)
214
+
215
+ ```bash
216
+ #!/bin/sh
217
+ npm run lint-staged # lint/format only staged files
218
+ ```
219
+
220
+ ### commit-msg (`.husky/commit-msg`)
221
+
222
+ ```bash
223
+ #!/bin/sh
224
+ npx --no -- commitlint --edit "$1" # validate commit message format
225
+ ```
226
+
227
+ ### lint-staged config (`package.json`)
228
+
229
+ ```json
230
+ {
231
+ "lint-staged": {
232
+ "*.{ts,tsx}": ["eslint --fix", "prettier --write"],
233
+ "*.{json,md,yaml}": ["prettier --write"]
234
+ }
235
+ }
236
+ ```
237
+
238
+ ## Aliases (`.gitconfig`)
239
+
240
+ ```ini
241
+ [alias]
242
+ st = status
243
+ co = checkout
244
+ br = branch
245
+ lg = log --oneline --decorate --graph --all
246
+ last = log -1 HEAD
247
+ unstage = reset HEAD --
248
+ aliases = config --get-regexp alias
249
+ ```
250
+
251
+ ## Safety Rules
252
+
253
+ 1. **Never force-push to `main`** or any shared branch
254
+ 2. **Never commit directly to `main`** in team projects
255
+ 3. **Never rebase published commits** — rebase only local commits
256
+ 4. **Never skip hooks** (`--no-verify`) — fix the underlying issue instead
257
+ 5. **Stage specific files** — avoid `git add .` which may include secrets
258
+ 6. **One logical change per commit** — makes bisect and revert possible
@@ -0,0 +1,202 @@
1
+
2
+ Apache License
3
+ Version 2.0, January 2004
4
+ http://www.apache.org/licenses/
5
+
6
+ TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
7
+
8
+ 1. Definitions.
9
+
10
+ "License" shall mean the terms and conditions for use, reproduction,
11
+ and distribution as defined by Sections 1 through 9 of this document.
12
+
13
+ "Licensor" shall mean the copyright owner or entity authorized by
14
+ the copyright owner that is granting the License.
15
+
16
+ "Legal Entity" shall mean the union of the acting entity and all
17
+ other entities that control, are controlled by, or are under common
18
+ control with that entity. For the purposes of this definition,
19
+ "control" means (i) the power, direct or indirect, to cause the
20
+ direction or management of such entity, whether by contract or
21
+ otherwise, or (ii) ownership of fifty percent (50%) or more of the
22
+ outstanding shares, or (iii) beneficial ownership of such entity.
23
+
24
+ "You" (or "Your") shall mean an individual or Legal Entity
25
+ exercising permissions granted by this License.
26
+
27
+ "Source" form shall mean the preferred form for making modifications,
28
+ including but not limited to software source code, documentation
29
+ source, and configuration files.
30
+
31
+ "Object" form shall mean any form resulting from mechanical
32
+ transformation or translation of a Source form, including but
33
+ not limited to compiled object code, generated documentation,
34
+ and conversions to other media types.
35
+
36
+ "Work" shall mean the work of authorship, whether in Source or
37
+ Object form, made available under the License, as indicated by a
38
+ copyright notice that is included in or attached to the work
39
+ (an example is provided in the Appendix below).
40
+
41
+ "Derivative Works" shall mean any work, whether in Source or Object
42
+ form, that is based on (or derived from) the Work and for which the
43
+ editorial revisions, annotations, elaborations, or other modifications
44
+ represent, as a whole, an original work of authorship. For the purposes
45
+ of this License, Derivative Works shall not include works that remain
46
+ separable from, or merely link (or bind by name) to the interfaces of,
47
+ the Work and Derivative Works thereof.
48
+
49
+ "Contribution" shall mean any work of authorship, including
50
+ the original version of the Work and any modifications or additions
51
+ to that Work or Derivative Works thereof, that is intentionally
52
+ submitted to Licensor for inclusion in the Work by the copyright owner
53
+ or by an individual or Legal Entity authorized to submit on behalf of
54
+ the copyright owner. For the purposes of this definition, "submitted"
55
+ means any form of electronic, verbal, or written communication sent
56
+ to the Licensor or its representatives, including but not limited to
57
+ communication on electronic mailing lists, source code control systems,
58
+ and issue tracking systems that are managed by, or on behalf of, the
59
+ Licensor for the purpose of discussing and improving the Work, but
60
+ excluding communication that is conspicuously marked or otherwise
61
+ designated in writing by the copyright owner as "Not a Contribution."
62
+
63
+ "Contributor" shall mean Licensor and any individual or Legal Entity
64
+ on behalf of whom a Contribution has been received by Licensor and
65
+ subsequently incorporated within the Work.
66
+
67
+ 2. Grant of Copyright License. Subject to the terms and conditions of
68
+ this License, each Contributor hereby grants to You a perpetual,
69
+ worldwide, non-exclusive, no-charge, royalty-free, irrevocable
70
+ copyright license to reproduce, prepare Derivative Works of,
71
+ publicly display, publicly perform, sublicense, and distribute the
72
+ Work and such Derivative Works in Source or Object form.
73
+
74
+ 3. Grant of Patent License. Subject to the terms and conditions of
75
+ this License, each Contributor hereby grants to You a perpetual,
76
+ worldwide, non-exclusive, no-charge, royalty-free, irrevocable
77
+ (except as stated in this section) patent license to make, have made,
78
+ use, offer to sell, sell, import, and otherwise transfer the Work,
79
+ where such license applies only to those patent claims licensable
80
+ by such Contributor that are necessarily infringed by their
81
+ Contribution(s) alone or by combination of their Contribution(s)
82
+ with the Work to which such Contribution(s) was submitted. If You
83
+ institute patent litigation against any entity (including a
84
+ cross-claim or counterclaim in a lawsuit) alleging that the Work
85
+ or a Contribution incorporated within the Work constitutes direct
86
+ or contributory patent infringement, then any patent licenses
87
+ granted to You under this License for that Work shall terminate
88
+ as of the date such litigation is filed.
89
+
90
+ 4. Redistribution. You may reproduce and distribute copies of the
91
+ Work or Derivative Works thereof in any medium, with or without
92
+ modifications, and in Source or Object form, provided that You
93
+ meet the following conditions:
94
+
95
+ (a) You must give any other recipients of the Work or
96
+ Derivative Works a copy of this License; and
97
+
98
+ (b) You must cause any modified files to carry prominent notices
99
+ stating that You changed the files; and
100
+
101
+ (c) You must retain, in the Source form of any Derivative Works
102
+ that You distribute, all copyright, patent, trademark, and
103
+ attribution notices from the Source form of the Work,
104
+ excluding those notices that do not pertain to any part of
105
+ the Derivative Works; and
106
+
107
+ (d) If the Work includes a "NOTICE" text file as part of its
108
+ distribution, then any Derivative Works that You distribute must
109
+ include a readable copy of the attribution notices contained
110
+ within such NOTICE file, excluding those notices that do not
111
+ pertain to any part of the Derivative Works, in at least one
112
+ of the following places: within a NOTICE text file distributed
113
+ as part of the Derivative Works; within the Source form or
114
+ documentation, if provided along with the Derivative Works; or,
115
+ within a display generated by the Derivative Works, if and
116
+ wherever such third-party notices normally appear. The contents
117
+ of the NOTICE file are for informational purposes only and
118
+ do not modify the License. You may add Your own attribution
119
+ notices within Derivative Works that You distribute, alongside
120
+ or as an addendum to the NOTICE text from the Work, provided
121
+ that such additional attribution notices cannot be construed
122
+ as modifying the License.
123
+
124
+ You may add Your own copyright statement to Your modifications and
125
+ may provide additional or different license terms and conditions
126
+ for use, reproduction, or distribution of Your modifications, or
127
+ for any such Derivative Works as a whole, provided Your use,
128
+ reproduction, and distribution of the Work otherwise complies with
129
+ the conditions stated in this License.
130
+
131
+ 5. Submission of Contributions. Unless You explicitly state otherwise,
132
+ any Contribution intentionally submitted for inclusion in the Work
133
+ by You to the Licensor shall be under the terms and conditions of
134
+ this License, without any additional terms or conditions.
135
+ Notwithstanding the above, nothing herein shall supersede or modify
136
+ the terms of any separate license agreement you may have executed
137
+ with Licensor regarding such Contributions.
138
+
139
+ 6. Trademarks. This License does not grant permission to use the trade
140
+ names, trademarks, service marks, or product names of the Licensor,
141
+ except as required for reasonable and customary use in describing the
142
+ origin of the Work and reproducing the content of the NOTICE file.
143
+
144
+ 7. Disclaimer of Warranty. Unless required by applicable law or
145
+ agreed to in writing, Licensor provides the Work (and each
146
+ Contributor provides its Contributions) on an "AS IS" BASIS,
147
+ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
148
+ implied, including, without limitation, any warranties or conditions
149
+ of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
150
+ PARTICULAR PURPOSE. You are solely responsible for determining the
151
+ appropriateness of using or redistributing the Work and assume any
152
+ risks associated with Your exercise of permissions under this License.
153
+
154
+ 8. Limitation of Liability. In no event and under no legal theory,
155
+ whether in tort (including negligence), contract, or otherwise,
156
+ unless required by applicable law (such as deliberate and grossly
157
+ negligent acts) or agreed to in writing, shall any Contributor be
158
+ liable to You for damages, including any direct, indirect, special,
159
+ incidental, or consequential damages of any character arising as a
160
+ result of this License or out of the use or inability to use the
161
+ Work (including but not limited to damages for loss of goodwill,
162
+ work stoppage, computer failure or malfunction, or any and all
163
+ other commercial damages or losses), even if such Contributor
164
+ has been advised of the possibility of such damages.
165
+
166
+ 9. Accepting Warranty or Additional Liability. While redistributing
167
+ the Work or Derivative Works thereof, You may choose to offer,
168
+ and charge a fee for, acceptance of support, warranty, indemnity,
169
+ or other liability obligations and/or rights consistent with this
170
+ License. However, in accepting such obligations, You may act only
171
+ on Your own behalf and on Your sole responsibility, not on behalf
172
+ of any other Contributor, and only if You agree to indemnify,
173
+ defend, and hold each Contributor harmless for any liability
174
+ incurred by, or claims asserted against, such Contributor by reason
175
+ of your accepting any such warranty or additional liability.
176
+
177
+ END OF TERMS AND CONDITIONS
178
+
179
+ APPENDIX: How to apply the Apache License to your work.
180
+
181
+ To apply the Apache License to your work, attach the following
182
+ boilerplate notice, with the fields enclosed by brackets "[]"
183
+ replaced with your own identifying information. (Don't include
184
+ the brackets!) The text should be enclosed in the appropriate
185
+ comment syntax for the file format. We also recommend that a
186
+ file or class name and description of purpose be included on the
187
+ same "printed page" as the copyright notice for easier
188
+ identification within third-party archives.
189
+
190
+ Copyright [yyyy] [name of copyright owner]
191
+
192
+ Licensed under the Apache License, Version 2.0 (the "License");
193
+ you may not use this file except in compliance with the License.
194
+ You may obtain a copy of the License at
195
+
196
+ http://www.apache.org/licenses/LICENSE-2.0
197
+
198
+ Unless required by applicable law or agreed to in writing, software
199
+ distributed under the License is distributed on an "AS IS" BASIS,
200
+ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
201
+ See the License for the specific language governing permissions and
202
+ limitations under the License.
@@ -0,0 +1,236 @@
1
+ ---
2
+ name: mcp-builder
3
+ description: Guide for creating high-quality MCP (Model Context Protocol) servers that enable LLMs to interact with external services through well-designed tools. Use when building MCP servers to integrate external APIs or services, whether in Python (FastMCP) or Node/TypeScript (MCP SDK).
4
+ license: Complete terms in LICENSE.txt
5
+ ---
6
+
7
+ # MCP Server Development Guide
8
+
9
+ ## Overview
10
+
11
+ Create MCP (Model Context Protocol) servers that enable LLMs to interact with external services through well-designed tools. The quality of an MCP server is measured by how well it enables LLMs to accomplish real-world tasks.
12
+
13
+ ---
14
+
15
+ # Process
16
+
17
+ ## 🚀 High-Level Workflow
18
+
19
+ Creating a high-quality MCP server involves four main phases:
20
+
21
+ ### Phase 1: Deep Research and Planning
22
+
23
+ #### 1.1 Understand Modern MCP Design
24
+
25
+ **API Coverage vs. Workflow Tools:**
26
+ Balance comprehensive API endpoint coverage with specialized workflow tools. Workflow tools can be more convenient for specific tasks, while comprehensive coverage gives agents flexibility to compose operations. Performance varies by client—some clients benefit from code execution that combines basic tools, while others work better with higher-level workflows. When uncertain, prioritize comprehensive API coverage.
27
+
28
+ **Tool Naming and Discoverability:**
29
+ Clear, descriptive tool names help agents find the right tools quickly. Use consistent prefixes (e.g., `github_create_issue`, `github_list_repos`) and action-oriented naming.
30
+
31
+ **Context Management:**
32
+ Agents benefit from concise tool descriptions and the ability to filter/paginate results. Design tools that return focused, relevant data. Some clients support code execution which can help agents filter and process data efficiently.
33
+
34
+ **Actionable Error Messages:**
35
+ Error messages should guide agents toward solutions with specific suggestions and next steps.
36
+
37
+ #### 1.2 Study MCP Protocol Documentation
38
+
39
+ **Navigate the MCP specification:**
40
+
41
+ Start with the sitemap to find relevant pages: `https://modelcontextprotocol.io/sitemap.xml`
42
+
43
+ Then fetch specific pages with `.md` suffix for markdown format (e.g., `https://modelcontextprotocol.io/specification/draft.md`).
44
+
45
+ Key pages to review:
46
+ - Specification overview and architecture
47
+ - Transport mechanisms (streamable HTTP, stdio)
48
+ - Tool, resource, and prompt definitions
49
+
50
+ #### 1.3 Study Framework Documentation
51
+
52
+ **Recommended stack:**
53
+ - **Language**: TypeScript (high-quality SDK support and good compatibility in many execution environments e.g. MCPB. Plus AI models are good at generating TypeScript code, benefiting from its broad usage, static typing and good linting tools)
54
+ - **Transport**: Streamable HTTP for remote servers, using stateless JSON (simpler to scale and maintain, as opposed to stateful sessions and streaming responses). stdio for local servers.
55
+
56
+ **Load framework documentation:**
57
+
58
+ - **MCP Best Practices**: [📋 View Best Practices](./reference/mcp_best_practices.md) - Core guidelines
59
+
60
+ **For TypeScript (recommended):**
61
+ - **TypeScript SDK**: Use WebFetch to load `https://raw.githubusercontent.com/modelcontextprotocol/typescript-sdk/main/README.md`
62
+ - [⚡ TypeScript Guide](./reference/node_mcp_server.md) - TypeScript patterns and examples
63
+
64
+ **For Python:**
65
+ - **Python SDK**: Use WebFetch to load `https://raw.githubusercontent.com/modelcontextprotocol/python-sdk/main/README.md`
66
+ - [🐍 Python Guide](./reference/python_mcp_server.md) - Python patterns and examples
67
+
68
+ #### 1.4 Plan Your Implementation
69
+
70
+ **Understand the API:**
71
+ Review the service's API documentation to identify key endpoints, authentication requirements, and data models. Use web search and WebFetch as needed.
72
+
73
+ **Tool Selection:**
74
+ Prioritize comprehensive API coverage. List endpoints to implement, starting with the most common operations.
75
+
76
+ ---
77
+
78
+ ### Phase 2: Implementation
79
+
80
+ #### 2.1 Set Up Project Structure
81
+
82
+ See language-specific guides for project setup:
83
+ - [⚡ TypeScript Guide](./reference/node_mcp_server.md) - Project structure, package.json, tsconfig.json
84
+ - [🐍 Python Guide](./reference/python_mcp_server.md) - Module organization, dependencies
85
+
86
+ #### 2.2 Implement Core Infrastructure
87
+
88
+ Create shared utilities:
89
+ - API client with authentication
90
+ - Error handling helpers
91
+ - Response formatting (JSON/Markdown)
92
+ - Pagination support
93
+
94
+ #### 2.3 Implement Tools
95
+
96
+ For each tool:
97
+
98
+ **Input Schema:**
99
+ - Use Zod (TypeScript) or Pydantic (Python)
100
+ - Include constraints and clear descriptions
101
+ - Add examples in field descriptions
102
+
103
+ **Output Schema:**
104
+ - Define `outputSchema` where possible for structured data
105
+ - Use `structuredContent` in tool responses (TypeScript SDK feature)
106
+ - Helps clients understand and process tool outputs
107
+
108
+ **Tool Description:**
109
+ - Concise summary of functionality
110
+ - Parameter descriptions
111
+ - Return type schema
112
+
113
+ **Implementation:**
114
+ - Async/await for I/O operations
115
+ - Proper error handling with actionable messages
116
+ - Support pagination where applicable
117
+ - Return both text content and structured data when using modern SDKs
118
+
119
+ **Annotations:**
120
+ - `readOnlyHint`: true/false
121
+ - `destructiveHint`: true/false
122
+ - `idempotentHint`: true/false
123
+ - `openWorldHint`: true/false
124
+
125
+ ---
126
+
127
+ ### Phase 3: Review and Test
128
+
129
+ #### 3.1 Code Quality
130
+
131
+ Review for:
132
+ - No duplicated code (DRY principle)
133
+ - Consistent error handling
134
+ - Full type coverage
135
+ - Clear tool descriptions
136
+
137
+ #### 3.2 Build and Test
138
+
139
+ **TypeScript:**
140
+ - Run `npm run build` to verify compilation
141
+ - Test with MCP Inspector: `npx @modelcontextprotocol/inspector`
142
+
143
+ **Python:**
144
+ - Verify syntax: `python -m py_compile your_server.py`
145
+ - Test with MCP Inspector
146
+
147
+ See language-specific guides for detailed testing approaches and quality checklists.
148
+
149
+ ---
150
+
151
+ ### Phase 4: Create Evaluations
152
+
153
+ After implementing your MCP server, create comprehensive evaluations to test its effectiveness.
154
+
155
+ **Load [✅ Evaluation Guide](./reference/evaluation.md) for complete evaluation guidelines.**
156
+
157
+ #### 4.1 Understand Evaluation Purpose
158
+
159
+ Use evaluations to test whether LLMs can effectively use your MCP server to answer realistic, complex questions.
160
+
161
+ #### 4.2 Create 10 Evaluation Questions
162
+
163
+ To create effective evaluations, follow the process outlined in the evaluation guide:
164
+
165
+ 1. **Tool Inspection**: List available tools and understand their capabilities
166
+ 2. **Content Exploration**: Use READ-ONLY operations to explore available data
167
+ 3. **Question Generation**: Create 10 complex, realistic questions
168
+ 4. **Answer Verification**: Solve each question yourself to verify answers
169
+
170
+ #### 4.3 Evaluation Requirements
171
+
172
+ Ensure each question is:
173
+ - **Independent**: Not dependent on other questions
174
+ - **Read-only**: Only non-destructive operations required
175
+ - **Complex**: Requiring multiple tool calls and deep exploration
176
+ - **Realistic**: Based on real use cases humans would care about
177
+ - **Verifiable**: Single, clear answer that can be verified by string comparison
178
+ - **Stable**: Answer won't change over time
179
+
180
+ #### 4.4 Output Format
181
+
182
+ Create an XML file with this structure:
183
+
184
+ ```xml
185
+ <evaluation>
186
+ <qa_pair>
187
+ <question>Find discussions about AI model launches with animal codenames. One model needed a specific safety designation that uses the format ASL-X. What number X was being determined for the model named after a spotted wild cat?</question>
188
+ <answer>3</answer>
189
+ </qa_pair>
190
+ <!-- More qa_pairs... -->
191
+ </evaluation>
192
+ ```
193
+
194
+ ---
195
+
196
+ # Reference Files
197
+
198
+ ## 📚 Documentation Library
199
+
200
+ Load these resources as needed during development:
201
+
202
+ ### Core MCP Documentation (Load First)
203
+ - **MCP Protocol**: Start with sitemap at `https://modelcontextprotocol.io/sitemap.xml`, then fetch specific pages with `.md` suffix
204
+ - [📋 MCP Best Practices](./reference/mcp_best_practices.md) - Universal MCP guidelines including:
205
+ - Server and tool naming conventions
206
+ - Response format guidelines (JSON vs Markdown)
207
+ - Pagination best practices
208
+ - Transport selection (streamable HTTP vs stdio)
209
+ - Security and error handling standards
210
+
211
+ ### SDK Documentation (Load During Phase 1/2)
212
+ - **Python SDK**: Fetch from `https://raw.githubusercontent.com/modelcontextprotocol/python-sdk/main/README.md`
213
+ - **TypeScript SDK**: Fetch from `https://raw.githubusercontent.com/modelcontextprotocol/typescript-sdk/main/README.md`
214
+
215
+ ### Language-Specific Implementation Guides (Load During Phase 2)
216
+ - [🐍 Python Implementation Guide](./reference/python_mcp_server.md) - Complete Python/FastMCP guide with:
217
+ - Server initialization patterns
218
+ - Pydantic model examples
219
+ - Tool registration with `@mcp.tool`
220
+ - Complete working examples
221
+ - Quality checklist
222
+
223
+ - [⚡ TypeScript Implementation Guide](./reference/node_mcp_server.md) - Complete TypeScript guide with:
224
+ - Project structure
225
+ - Zod schema patterns
226
+ - Tool registration with `server.registerTool`
227
+ - Complete working examples
228
+ - Quality checklist
229
+
230
+ ### Evaluation Guide (Load During Phase 4)
231
+ - [✅ Evaluation Guide](./reference/evaluation.md) - Complete evaluation creation guide with:
232
+ - Question creation guidelines
233
+ - Answer verification strategies
234
+ - XML format specifications
235
+ - Example questions and answers
236
+ - Running an evaluation with the provided scripts