@vantageos/mcp-boilerplate 0.1.2 → 0.2.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 (50) hide show
  1. package/.claude-plugin/plugin.json +16 -8
  2. package/.mcp.json +8 -0
  3. package/CHANGELOG.md +55 -1
  4. package/README.fr.md +177 -142
  5. package/README.md +170 -133
  6. package/dist/auth.d.ts +20 -10
  7. package/dist/auth.js +9 -8
  8. package/dist/config.d.ts +10 -3
  9. package/dist/config.js +31 -3
  10. package/dist/exampleItems.d.ts +5 -4
  11. package/dist/exampleItems.js +3 -0
  12. package/dist/http.js +11 -1
  13. package/dist/httpApp.d.ts +23 -30
  14. package/dist/httpApp.js +73 -74
  15. package/dist/i18n.d.ts +6 -0
  16. package/dist/i18n.js +9 -0
  17. package/dist/locales/en.json +9 -0
  18. package/dist/locales/fr.json +9 -0
  19. package/dist/mcpServerFactory.d.ts +42 -41
  20. package/dist/mcpServerFactory.js +114 -165
  21. package/dist/oauth/authorizationServer.d.ts +56 -0
  22. package/dist/oauth/authorizationServer.js +423 -0
  23. package/dist/oauth/clerk.d.ts +15 -0
  24. package/dist/oauth/clerk.js +59 -0
  25. package/dist/oauth/clientRegistry.d.ts +50 -0
  26. package/dist/oauth/clientRegistry.js +203 -0
  27. package/dist/oauth/codeStore.d.ts +11 -0
  28. package/dist/oauth/codeStore.js +28 -0
  29. package/dist/oauth/picker.d.ts +11 -0
  30. package/dist/oauth/picker.js +67 -0
  31. package/dist/oauth/settings.d.ts +48 -0
  32. package/dist/oauth/settings.js +100 -0
  33. package/dist/oauth/tokenIssuer.d.ts +22 -0
  34. package/dist/oauth/tokenIssuer.js +61 -0
  35. package/dist/stdio.d.ts +7 -6
  36. package/dist/stdio.js +20 -19
  37. package/dist/tenancy.d.ts +16 -21
  38. package/dist/tenancy.js +12 -26
  39. package/dist/ui/uiResource.d.ts +36 -3
  40. package/dist/ui/uiResource.js +40 -6
  41. package/dist/version.d.ts +2 -0
  42. package/dist/version.js +8 -0
  43. package/docs/architecture.md +82 -0
  44. package/docs/oauth-stores.md +60 -0
  45. package/examples/oauth.env.example +25 -0
  46. package/mcp.json +19 -0
  47. package/package.json +22 -13
  48. package/plugin.json +43 -0
  49. package/scripts/plugin-manifest.source.json +35 -0
  50. package/skills/connect-mcp-server/SKILL.md +40 -0
package/skills/connect-mcp-server/SKILL.md ADDED
@@ -0,0 +1,40 @@
1
+ ---
2
+ name: connect-mcp-server
3
+ description: Connect this MCP server to Claude Code, ChatGPT or any MCP client, and check the connection works. Use when the user says "connect the server", "set up the MCP boilerplate", "add this MCP server", or reports that the tools do not appear.
4
+ ---
5
+
6
+ # Connect the MCP boilerplate server
7
+
8
+ This plugin ships one MCP server (`mcp-boilerplate`) with three tools: `ping`, `list_items`
9
+ and `render_items_ui`. Follow the path that matches where it runs.
10
+
11
+ ## 1. Pick the transport
12
+
13
+ - **Local (stdio)**: no account, no network. Run `npx -y @vantageos/mcp-boilerplate` as the
14
+ server command. The caller is the local process, so there is no sign-in.
15
+ - **Remote (Streamable HTTP)**: a deployed server at `https://<your-host>/mcp`. It signs the
16
+ person in with Clerk and asks them to pick an organisation before any tool works.
17
+
18
+ ## 2. Connect a remote server
19
+
20
+ 1. Take the server URL from the deployment. The plugin reads it from `MCP_BOILERPLATE_URL`
21
+ (Claude Code) or from `mcp.json` (ChatGPT); the shipped value is a placeholder.
22
+ 2. In Claude Code, export the variable, then reload the plugin:
23
+ `export MCP_BOILERPLATE_URL=https://<your-host>/mcp`.
24
+ 3. Start the connection. A browser window opens: sign in, choose the organisation, approve.
25
+ 4. A client that publishes a Client ID Metadata Document connects directly; any other client
26
+ registers itself on the server's `/register` endpoint first. Nothing to configure by hand.
27
+
28
+ ## 3. Check it works
29
+
30
+ 1. Call `ping`. The reply is `pong`.
31
+ 2. Call `list_items`. A signed-in person sees only the items of the chosen organisation.
32
+ 3. Call `render_items_ui`. A host that supports MCP Apps shows the widget; any other host
33
+ shows the markdown list that comes with the result.
34
+
35
+ ## If something fails
36
+
37
+ - `503 temporarily_unavailable` on sign-in: the server is missing configuration. The names of
38
+ the missing variables are in the server log (never the values).
39
+ - `401` on `/mcp`: the token expired or was minted for another server. Reconnect.
40
+ - Tools missing: the client has not reloaded. Reload the plugin or restart the client.