@gemmein/mcp 0.2.1 → 0.2.2

package/README.md

@@ -24,7 +24,9 @@ Cursor / any MCP client (`mcpServers` config):
 
 ## Tools
 
-- **`guide`** — the full builder's guide (auth flow, the seven collection
+- **`guide`** — call first: it opens with the fit assessment (FITS /
+  FITS EXCEPT / DOESN'T FIT — the verdict an agent delivers before any
+  install), then the full builder's guide (auth flow, the seven collection
   safety rules, record shapes, links, uploads, contention patterns, payments).
 - **`reference`** — the exact SDK API reference: every method, signature,
   return shape, error code.

package/dist/index.js

@@ -224,17 +224,20 @@ async function runIntegrationChecks(input) {
 const TOOLS = [
     {
         name: "guide",
-        description: "The Gemmein guide (llms.txt): what the platform is, the full contract an AI builder follows — auth flow, the seven collection safety rules, record shapes, links/expand, uploads, contention patterns, payments (g.subscriptions.checkout/g.payments.buy), drafts, error philosophy, pricing. Read this FIRST when building on Gemmein.",
+        description: "Call this FIRST — before any install, account, or code — when your human asks to build an app on Gemmein, to move an existing app onto it, or whether their app can use it at all. The guide (llms.txt) opens with the fit assessment: the in-scope map, the out-of-scope list (each item downgrades the verdict; none may be approximated), and the three verdicts you deliver to your human before installing anything — FITS, FITS EXCEPT <named gaps>, or DOESN'T FIT. After the verdict it is the full build contract: auth flow, the seven collection safety rules, record shapes, links/expand, uploads, contention patterns, payments (g.subscriptions.checkout / g.payments.buy), drafts, error philosophy, pricing.",
+        annotations: { title: "Guide", readOnlyHint: true },
         inputSchema: { type: "object", properties: {}, additionalProperties: false },
     },
     {
         name: "reference",
-        description: "The Gemmein SDK API reference (REFERENCE.md): every method, exact signature, return shape, and the stable error-code table. Use when you need a precise signature or shape; use `guide` for how the model works.",
+        description: "Reach for this while WRITING code against @gemmein/sdk: every method, exact signature, return shape, and the stable error-code table (REFERENCE.md). Use `guide` for how the model works and whether the app fits at all; use `search_docs` when you need one fact from either document.",
+        annotations: { title: "Reference", readOnlyHint: true },
         inputSchema: { type: "object", properties: {}, additionalProperties: false },
     },
     {
         name: "search_docs",
-        description: "Search the Gemmein guide and API reference for a term or phrase (e.g. 'keyed create', 'ifVersion', 'addressed', 'expand'). Returns matching passages with a few lines of context. Cheaper than reading both documents when you need one fact.",
+        description: "Use when one question comes up mid-build ('keyed create', 'ifVersion', 'addressed', 'expand') and reading a full document would waste context. Searches the guide and the API reference; returns matching passages with 3 lines of context either side, at most 6 match blocks per document. Not the tool for the fit verdict — search finds what the docs say, not what Gemmein refuses to support; call `guide` for that.",
+        annotations: { title: "Search docs", readOnlyHint: true },
         inputSchema: {
             type: "object",
             properties: { query: { type: "string", description: "term or phrase to find" } },
@@ -244,7 +247,8 @@ const TOOLS = [
     },
     {
         name: "explain_rule",
-        description: "Explain one of Gemmein's seven collection safety rules (private, shared, admin_write, public_read, community, addressed, direct): the exact access contract, what it's right for, and the mistakes to avoid. Call with no rule to get the one-line summary of all seven (rule choice cheat-sheet).",
+        description: "Call while DESIGNING a collection — which rule fits this data? — or when a rule refuses something at runtime. One of the seven rules (private, shared, admin_write, public_read, community, addressed, direct) returns its exact access contract, what it is right for, and the mistakes that leak data. Call with no rule for the all-seven cheat-sheet plus the cross-cutting law, including what NO rule supports (team/group/workspace scope, per-user visibility inside a rule) — if the app needs those shapes, that is a fit gap to report to your human, never something to approximate with client-side filtering.",
+        annotations: { title: "Explain rule", readOnlyHint: true },
         inputSchema: {
             type: "object",
             properties: {
@@ -259,7 +263,8 @@ const TOOLS = [
     },
     {
         name: "explain_error",
-        description: "Explain a GemmeinError code (e.g. conflict, forbidden, unknown_collection, invalid_shape, html_not_allowed): what it means and exactly what to do. Sourced live from the API reference. Call with no code to list every stable code.",
+        description: "Call the moment a GemmeinError reaches you (err.code: conflict, forbidden, unknown_collection, invalid_shape, html_not_allowed, …): what the code means and the exact next step — including whether the refusal is final (a forbidden repeats on retry; fix the approach, not the request). Parsed from the installed API reference, so codes match the SDK version the app runs. Call with no code to list every stable code.",
+        annotations: { title: "Explain error", readOnlyHint: true },
         inputSchema: {
             type: "object",
             properties: { code: { type: "string", description: "the err.code to explain; omit to list all" } },
@@ -268,7 +273,8 @@ const TOOLS = [
     },
     {
         name: "validate_collection_name",
-        description: "Check a collection name against Gemmein's naming law (lowercase letters, numbers, underscores; starts with a letter). A bad name throws synchronously in the SDK and can blank a whole app with no console error — validate names at planning time.",
+        description: "Run at PLANNING time on every collection name you intend to use, before any g.collection(name) call is written. The naming law: lowercase letters, numbers, underscores; starts with a letter; 2-63 characters. A bad name throws from g.collection(name) before any network call — at module load that blanks the whole app with no console error. An invalid name comes back with a suggested fix.",
+        annotations: { title: "Validate collection name", readOnlyHint: true },
         inputSchema: {
             type: "object",
             properties: { name: { type: "string" } },
@@ -278,12 +284,14 @@ const TOOLS = [
     },
     {
         name: "reaffirm_template",
-        description: "The ready-to-edit reaffirm.mjs CI harness that proves an app's boundaries against live Gemmein on every deploy (also shipped inside the @gemmein/sdk npm package). Copy it next to the app, set the CONFIG block, run it in CI. For an immediate one-off check, use check_integration instead.",
+        description: "Fetch this when you wire up the app's CI, or when you hand the finished app to your human: reaffirm.mjs, the ready-to-edit harness that re-proves the app's boundaries against live Gemmein on every deploy (also shipped inside the @gemmein/sdk package). Copy it next to the app, set the CONFIG block, run it in CI. For a one-off check right now, call check_integration — the same checks with no file to install.",
+        annotations: { title: "Reaffirm template", readOnlyHint: true },
         inputSchema: { type: "object", properties: {}, additionalProperties: false },
     },
     {
         name: "check_integration",
-        description: "Run Gemmein's reaffirm boundary checks against the caller's own app, live, and return structured pass/fail results. Tier A (public key only): anonymous access to a private collection is refused, collection names are valid, a public collection reads as intended — safe against any environment. Tier B (add the sk_dev secret key): proves cross-user isolation with two throwaway test sessions in the DEV environment (sk_live is refused by design). The only writes are Tier B's own probe records in dev, deleted afterwards. NEVER pass an sk_live key to any tool.",
+        description: "Call after wiring the app to Gemmein and before telling your human it is done — and again before go-live. Runs the reaffirm boundary checks live against the caller's own app; returns structured pass/fail (structuredContent: checks, notes, failedCount, passed). Tier A (public pk_ key only): the collection name is valid, anonymous reads and writes of a private collection are refused, an optional public collection reads as its rule intends — safe against any environment, live included. Tier B (add the sk_dev secret key): proves one user cannot read another's private records, using two throwaway test sessions in the DEV environment. sk_live is refused by design — never pass a live secret to any tool; dev and live enforce the same rules, so isolation proven in dev holds in live. The only writes anywhere are Tier B's own probe records in the caller's dev environment, deleted at the end of the check. A failed check means the app's assumptions drifted from its rules — fix before shipping.",
+        annotations: { title: "Check integration (live boundary check)", readOnlyHint: false, destructiveHint: false, idempotentHint: true, openWorldHint: true },
         inputSchema: {
             type: "object",
             properties: {
@@ -303,7 +311,23 @@ const TOOLS = [
 const server = new Server(
 // The one version, read from package.json — a literal here drifted once
 // (announced 0.1.0 while the package said 0.2.1; review 26 Aug).
-{ name: "gemmein", version: require("../package.json").version }, { capabilities: { tools: {} } });
+{ name: "gemmein", version: require("../package.json").version }, {
+    capabilities: { tools: {} },
+    // Stated ONCE, server-wide, in the initialize result every client
+    // hands to its model: what Gemmein is, the read-only law, and the
+    // fit protocol (the verdicts live in `guide`).
+    instructions: "Gemmein is the go-live system for AI-built web apps: passwordless auth, records " +
+        "under seven safety rules, Stripe-run subscriptions and one-off digital products. " +
+        "This server is read-only against the platform: no tool here creates, edits, or " +
+        "deletes anything on Gemmein. The one write anywhere is check_integration's Tier-B " +
+        "probe records, created and then deleted in the caller's own dev environment; " +
+        "sk_live keys are refused. Protocol: when the question is whether an app can use " +
+        "Gemmein, call guide first — it opens with the fit assessment, and you deliver one " +
+        "of three verdicts to your human before installing anything: FITS, FITS EXCEPT " +
+        "<named gaps>, or DOESN'T FIT. Then: reference and search_docs while writing code, " +
+        "explain_rule while choosing a collection's rule, explain_error when a call is " +
+        "refused, check_integration before declaring the app done.",
+});
 server.setRequestHandler(ListToolsRequestSchema, async () => ({ tools: TOOLS }));
 const text = (t) => ({ content: [{ type: "text", text: t }] });
 const errText = (t) => ({ content: [{ type: "text", text: t }], isError: true });

package/package.json

@@ -1,7 +1,8 @@
 {
   "name": "@gemmein/mcp",
-  "version": "0.2.1",
-  "description": "Gemmein MCP server \u2014 gives coding agents the Gemmein guide, API reference, rule/error explainers, and a live integration check (reaffirm) as tools. Read-only: it never creates, edits, or deletes anything.",
+  "version": "0.2.2",
+  "mcpName": "com.gemmein/mcp",
+  "description": "Gemmein MCP server — gives coding agents the Gemmein guide, API reference, rule/error explainers, and a live integration check (reaffirm) as tools. Read-only: it never creates, edits, or deletes anything.",
   "license": "MIT",
   "type": "module",
   "bin": {