@emseepea/server 0.3.0 → 0.3.2

package/README.md

@@ -19,19 +19,24 @@ package supports and what it does not support.
 import { createEmseepea, defineMappedTool, defineTool, serveEmseepea } from "@emseepea/server";
 import { z } from "zod";
 
-const peaVariety = z.object({
-  name: z.string(),
-  peaType: z.enum(["shelling", "snap"]),
-  growthHabit: z.enum(["bush", "climbing"]),
-  daysToMaturity: z.number().int().positive(),
+const outputSchema = z.object({
+  name: z.string().describe("Name of the pea variety."),
+  peaType: z.enum(["shelling", "snap"])
+    .describe("Whether the variety is grown for shelled peas or edible pods."),
+  growthHabit: z.enum(["bush", "climbing"])
+    .describe("Whether the plant grows as a bush or climbing vine."),
+  daysToMaturity: z.number().int().positive()
+    .describe("Approximate days from sowing until the first harvest."),
 });
 
 const getPeaVariety = defineTool({
   name: "get-pea-variety",
   access: "public",
   description: "Get the type, growth habit, and maturity time for one pea variety.",
-  inputSchema: z.object({ name: z.string() }),
-  outputSchema: peaVariety,
+  inputSchema: z.object({
+    name: z.string().describe("Pea variety to look up."),
+  }),
+  outputSchema,
   handler: ({ name }) => {
     const data = {
       name,
@@ -47,6 +52,9 @@ const app = createEmseepea({ name: "pea-guide", version: "1.0.0", tools: [getPea
 await serveEmseepea(app);
 ```
 
+Describe each public input and output property in terms useful to a model. Em
+See Pea includes Zod `.describe()` text in the MCP tool schema sent to clients.
+
 ## Discover Capability Modules at Startup
 
 Explicit registration still works. If you prefer one file per capability, put
@@ -84,8 +92,12 @@ export default (() => defineTool({
   name: "get-pea-variety",
   access: "public",
   description: "Get one pea variety.",
-  inputSchema: z.object({ name: z.string() }),
-  outputSchema: z.object({ name: z.string() }),
+  inputSchema: z.object({
+    name: z.string().describe("Pea variety to look up."),
+  }),
+  outputSchema: z.object({
+    name: z.string().describe("Name of the pea variety."),
+  }),
   handler: ({ name }) => ({ text: name, data: { name } }),
 })) satisfies CapabilityModuleFactory;
 ```
@@ -241,7 +253,7 @@ const getPeaVariety = defineTool({
   icons: [{ src: "https://garden.example/icons/pea.png", mimeType: "image/png" }],
   annotations: { readOnlyHint: true, openWorldHint: false },
   inputSchema: z.object({ name: z.string() }),
-  outputSchema: peaVariety,
+  outputSchema,
   handler,
 });
 ```
@@ -374,39 +386,36 @@ Prefer an open, bounded schema when the backend can add valid values
 independently.
 
 ```ts
-const backendCommand = z.object({ search: z.string().max(200) });
-const catalogueTaxon = z.object({
-  id: z.number().int().positive(),
-  name: z.string().max(200),
-  rank: z.string().max(40),
-  observations_count: z.number().int().nonnegative(),
+const inputSchema = z.object({
+  name: z.string().max(200).describe("Pea taxon to look up."),
 });
-const backendResult = z.object({
-  record: z.object({
-    id: z.number().int().positive(),
-    name: z.string().max(200),
-    rank: z.string().max(40),
-    observations_count: z.number().int().nonnegative(),
-  }),
+const backendInputSchema = z.object({ search: z.string().max(200) });
+const backendTaxon = z.object({
+  id: z.number().int().positive().describe("Provider identifier for the taxon."),
+  name: z.string().max(200).describe("Scientific name of the taxon."),
+  rank: z.string().max(40).describe("Taxonomic rank reported by the provider."),
+  observations_count: z.number().int().nonnegative()
+    .describe("Recorded observations, not an estimate of the wild population."),
+});
+const outputSchema = backendTaxon.extend({
+  source: z.literal("catalogue-service").describe("Data provider for this result."),
+});
+const backendOutputSchema = z.object({
+  record: backendTaxon,
 });
 
 const getPeaTaxon = defineMappedTool({
   name: "get-pea-taxon",
   access: "public",
   description: "Get a pea taxon from the catalogue service.",
-  inputSchema: z.object({ name: z.string().max(200) }),
-  outputSchema: catalogueTaxon,
-  backendInputSchema: backendCommand,
-  backendOutputSchema: backendResult,
+  inputSchema,
+  outputSchema,
+  backendInputSchema,
+  backendOutputSchema,
   mapInput: ({ name }) => ({ search: name }),
   adapter: async (command, { signal }) => backend.findTaxon(command, { signal }),
   mapOutput: ({ record }) => {
-    const data = {
-      id: record.id,
-      name: record.name,
-      rank: record.rank,
-      observations_count: record.observations_count,
-    };
+    const data = { ...record, source: "catalogue-service" as const };
     return { text: `${data.name} has rank ${data.rank} and ${data.observations_count} recorded observations.`, data };
   },
 });
@@ -610,7 +619,9 @@ const methodGuide = defineResourceTemplate({
 
 const growing = definePrompt({
   name: "growing-guide",
-  argsSchema: z.object({ topic: z.string().min(1) }),
+  argsSchema: z.object({
+    topic: z.string().min(1).describe("Pea-growing topic to explain."),
+  }),
   complete: {
     topic: (value) => ["sowing-depth", "plant-spacing"].filter((topic) => topic.startsWith(value)),
   },

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@emseepea/server",
-  "version": "0.3.0",
+  "version": "0.3.2",
   "description": "Fastify-first framework for Model Context Protocol 2026-07-28 servers over Streamable HTTP",
   "license": "MIT",
   "repository": {