vantage-peers-mcp 2.0.0 → 2.0.1

package/README.md

@@ -109,6 +109,71 @@ The server also reads `CONVEX_URL` from `.env.local` in the parent directory if
 ### Session (1)
 `set_summary`
 
+## Programmatic API (TypeScript)
+
+For external services that need type-safe access to VantagePeers functions:
+
+```bash
+npm install vantage-peers-mcp convex
+```
+
+```typescript
+import { fetchQuery, fetchMutation } from "convex/nextjs";
+import { api } from "vantage-peers-mcp/api";
+
+// Query memories with full type safety
+const memories = await fetchQuery(
+  api.memories.listMemories,
+  { namespace: "global", limit: 10 },
+  { url: process.env.CONVEX_URL }
+);
+
+// Send a message
+await fetchMutation(
+  api.messages.sendMessage,
+  { from: "pi", channel: "broadcast", content: "Hello from Studio" },
+  { url: process.env.CONVEX_URL }
+);
+```
+
+Requires `convex` as a peer dependency. Only public functions are exported.
+
+### Authentication with Deploy Keys
+
+For server-to-server access, use a Convex deploy key:
+
+1. Go to your [Convex dashboard](https://dashboard.convex.dev) > Settings > Deploy Keys
+2. Generate a new deploy key for your deployment
+3. Set it as an environment variable:
+
+```bash
+CONVEX_DEPLOY_KEY=prod:your-deploy-key-here
+```
+
+4. Use it with the Convex client:
+
+```typescript
+import { ConvexHttpClient } from "convex/browser";
+import { api } from "vantage-peers-mcp/api";
+
+const client = new ConvexHttpClient(process.env.CONVEX_URL!);
+
+// Query with type safety
+const memories = await client.query(api.memories.listMemories, {
+  namespace: "global",
+  limit: 10,
+});
+
+// Mutate with type safety
+await client.mutation(api.messages.sendMessage, {
+  from: "studio",
+  channel: "sigma",
+  content: "Task completed",
+});
+```
+
+**Security:** Never commit deploy keys to git. Use environment variables or a secrets manager.
+
 ## Requirements
 
 - Node.js >= 18