coaiajs 0.1.2 → 0.2.1

package/articles/technical/ioredis-vs-redis.md

@@ -0,0 +1,142 @@
+# ioredis vs node-redis: Technical Assessment for CoAiA.js
+
+> Package selection brief — Redis client for structural tension chart storage, session management, and MCP memory persistence
+
+## Summary & Recommendation
+
+**Use `ioredis` v5.4.x** for coaiajs. Despite Redis Inc. pushing `node-redis` as the official client, ioredis delivers superior ergonomics for our use case: URL-based connection strings (Upstash REST compatibility), built-in cluster support for future scaling, and a smoother pipelining API. The ~14M weekly downloads and battle-tested stability outweigh the marginal concurrency edge of node-redis that we don't need.
+
+**Pin:** `"ioredis": "^5.4.0"`
+
+## What We're Replacing
+
+Coaiapy uses `redis<=4.3.6` (Python redis-py) with a lazy-loading pattern:
+
+```python
+# coaiapy/coaiamodule.py — lazy import for Pythonista compatibility
+def _get_redis():
+    """Lazy import of redis module"""
+    import redis
+    return redis
+```
+
+The Python client connects via URL string and performs simple GET/SET with TTL for session data, chart state, and webhook coordination. coaia-narrative's MCP server (Redis-backed medicine wheel) also uses Redis for ceremony state.
+
+## Options Compared
+
+| Feature | ioredis v5.4 | node-redis v4.7 |
+|---------|-------------|-----------------|
+| Weekly npm downloads | ~14–15M | ~8–9M |
+| GitHub stars | ~15,000 | ~17,000 |
+| Connection from URL | `new Redis(url)` — native | `createClient({ url })` — native |
+| Upstash REST compat | Via `@upstash/redis` wrapper or direct URL | Via `@upstash/redis` wrapper |
+| GET/SET with TTL | `redis.set(key, val, 'EX', ttl)` | `client.set(key, val, { EX: ttl })` |
+| Pipelining | `redis.pipeline().set().get().exec()` | `client.multi().set().get().exec()` |
+| Cluster support | Built-in, first-class | Available but newer |
+| Auto-reconnect | Built-in with backoff | Built-in with strategy |
+| TypeScript | `@types/ioredis` bundled | Native types |
+| Concurrent 100-SET ops/sec | ~2,500 | ~3,800 |
+| Sequential GET ops/sec | ~8,700 | ~7,900 |
+| Lua scripting | First-class `defineCommand()` | Supported |
+| Streams API | Rich ergonomic API | Supported |
+
+## API Overview
+
+### Connection Pattern for coaiajs
+
+```typescript
+import Redis from 'ioredis';
+import { loadConfig } from '../config.js';
+
+// Connection from URL (matches coaiapy pattern)
+const config = loadConfig();
+const redis = new Redis(config.redisUrl ?? 'redis://localhost:6379');
+
+// With Upstash (TLS URL)
+const upstashRedis = new Redis(process.env.UPSTASH_REDIS_URL!, {
+  tls: { rejectUnauthorized: false },
+  lazyConnect: true,  // matches coaiapy's lazy pattern
+});
+```
+
+### Core Operations We Need
+
+```typescript
+// Session storage with TTL
+async function saveSession(sessionId: string, data: object, ttlSeconds = 3600): Promise<void> {
+  await redis.set(`session:${sessionId}`, JSON.stringify(data), 'EX', ttlSeconds);
+}
+
+async function loadSession(sessionId: string): Promise<object | null> {
+  const raw = await redis.get(`session:${sessionId}`);
+  return raw ? JSON.parse(raw) : null;
+}
+
+// Chart state persistence (coaia-narrative pattern)
+async function saveChart(chartId: string, chart: object): Promise<void> {
+  await redis.hset(`chart:${chartId}`, {
+    data: JSON.stringify(chart),
+    updatedAt: new Date().toISOString(),
+  });
+}
+
+// Pipeline for batch operations
+async function loadMultipleCharts(ids: string[]): Promise<Map<string, object>> {
+  const pipeline = redis.pipeline();
+  ids.forEach(id => pipeline.hgetall(`chart:${id}`));
+  const results = await pipeline.exec();
+  // ... process results
+}
+```
+
+### Lazy Connection Pattern (matching coaiapy)
+
+```typescript
+let _redis: Redis | null = null;
+
+export function getRedis(): Redis {
+  if (!_redis) {
+    const url = process.env.REDIS_URL ?? process.env.UPSTASH_REDIS_URL ?? 'redis://localhost:6379';
+    _redis = new Redis(url, { lazyConnect: true });
+  }
+  return _redis;
+}
+```
+
+## Integration Plan
+
+1. **Core module:** `src/redis.ts` — connection singleton, lazy init, URL-from-config
+2. **Session storage:** `src/session.ts` — GET/SET with TTL for webhook session management
+3. **Chart persistence:** `src/narrative/redis-store.ts` — HSET/HGETALL for structural tension charts
+4. **MCP memory:** `mcp/tools/memory.ts` — Redis-backed tool state for MCP servers
+5. **Graceful shutdown:** `redis.quit()` in process exit handlers
+
+## Version & Ecosystem
+
+| Metric | Value |
+|--------|-------|
+| Current version | 5.4.2 (March 2026) |
+| Weekly downloads | ~14.5M |
+| TypeScript | Built-in types since v5 |
+| Node.js compat | ≥14 (we target ≥20) |
+| Maintenance | Active, regular releases |
+| License | MIT |
+| Bundle size | ~85KB minified |
+
+## Why Not node-redis?
+
+1. **Connection API ergonomics**: ioredis accepts URL in constructor directly; node-redis requires `createClient()` factory
+2. **Cluster future-proofing**: ioredis has years of battle-tested cluster support
+3. **Pipelining**: ioredis pipeline API is cleaner for our batch chart operations
+4. **Lazy connect**: `lazyConnect: true` maps directly to coaiapy's lazy import pattern
+5. **Ecosystem**: Used by Bull, BullMQ, and most Redis-dependent MCP servers we integrate with
+
+The 3,800 vs 2,500 ops/sec concurrent difference in node-redis's favor is irrelevant — coaiajs is an agent framework, not a high-throughput data pipeline.
+
+## References
+
+- npm: https://www.npmjs.com/package/ioredis
+- GitHub: https://github.com/redis/ioredis
+- Benchmark: https://glama.ai/blog/2026-01-26-redis-vs-ioredis-vs-valkey-glide
+- npm trends: https://npmtrends.com/ioredis-vs-redis
+- Redis migration guide: https://redis.io/docs/latest/develop/clients/nodejs/migration/

package/articles/technical/langfuse-js-sdk-vs-rest.md

@@ -0,0 +1,191 @@
+# Langfuse JS SDK vs REST API: Technical Assessment for CoAiA.js
+
+> Package selection brief — LLM observability, tracing, and prompt management for CoAiA agent sessions
+
+## Summary & Recommendation
+
+**Use `langfuse` v4.x SDK** (`@langfuse/core` + `@langfuse/tracing`). The v4 rewrite (August 2025) brings OpenTelemetry-native tracing, modular packages, and direct integration with OpenAI — eliminating coaiapy's manual HTTP request overhead. The SDK handles batching, retries, and serialization that our REST wrapper currently does manually in `cofuse.py`.
+
+**Pin:** `"langfuse": "^4.0.0"` (pulls `@langfuse/core`, `@langfuse/tracing`)
+
+## What We're Replacing
+
+Coaiapy uses raw HTTP requests to the Langfuse REST API via Python `requests`:
+
+```python
+# coaiapy/cofuse.py — manual HTTP approach
+import requests
+from requests.auth import HTTPBasicAuth
+
+def create_session_and_save():
+    # Manual JSON construction, auth header assembly, error handling
+    response = requests.post(f"{base_url}/api/public/traces", 
+                            json=payload, 
+                            auth=HTTPBasicAuth(public_key, secret_key))
+
+def add_trace_node_and_save():
+    # More manual HTTP calls...
+
+def list_traces():
+    response = requests.get(f"{base_url}/api/public/traces", ...)
+```
+
+This pattern requires ~200 lines of boilerplate for authentication, serialization, error handling, and retry logic that the SDK provides out of the box.
+
+## Options Compared
+
+| Feature | Langfuse JS SDK v4 | REST API (manual) |
+|---------|-------------------|-------------------|
+| Setup complexity | `new Langfuse({ publicKey, secretKey })` | Manual auth headers, URL construction |
+| Trace creation | `langfuse.trace({ name, metadata })` | `POST /api/public/traces` + JSON body |
+| Span nesting | `trace.span({ name })` → `span.generation()` | Manual parent-child ID tracking |
+| OpenAI integration | `@langfuse/openai` drop-in wrapper | Manual extraction of token counts |
+| Batch flush | Automatic with configurable intervals | Manual batching implementation |
+| Retry logic | Built-in exponential backoff | Manual retry loops |
+| OpenTelemetry | Native OTEL span processor | Not available |
+| Type safety | Full TypeScript types | Manual interface definitions |
+| Prompt management | `langfuse.getPrompt()` | `GET /api/public/prompts` |
+| Scoring | `trace.score({ name, value })` | `POST /api/public/scores` + JSON body |
+| MCP server integration | Native via hosted MCP | Manual tool definitions |
+| Maintenance burden | ~5 lines setup | ~200+ lines of wrapper code |
+
+## API Overview
+
+### SDK Initialization
+
+```typescript
+import { Langfuse } from 'langfuse';
+import { loadConfig } from '../config.js';
+
+const config = loadConfig();
+const langfuse = new Langfuse({
+  publicKey: config.langfusePublicKey,
+  secretKey: config.langfuseSecretKey,
+  baseUrl: config.langfuseBaseUrl ?? 'https://cloud.langfuse.com',
+});
+```
+
+### Trace Creation (replacing cofuse.py create_session_and_save)
+
+```typescript
+// coaiapy equivalent: create_session_and_save()
+async function createAgentSession(sessionId: string, metadata: Record<string, unknown>) {
+  const trace = langfuse.trace({
+    id: sessionId,
+    name: `coaia-session-${sessionId}`,
+    metadata,
+    tags: ['coaiajs', 'agent-session'],
+  });
+
+  // Nested spans for pipeline steps
+  const span = trace.span({ name: 'pipeline-execution' });
+  
+  // Generation tracking (replaces add_trace_node_and_save)
+  const generation = span.generation({
+    name: 'llm-call',
+    model: 'gpt-5.4',
+    input: messages,
+    output: response,
+    usage: { promptTokens: 150, completionTokens: 300 },
+  });
+
+  generation.end();
+  span.end();
+  
+  return trace;
+}
+```
+
+### OpenAI Integration (automatic tracing)
+
+```typescript
+import { observeOpenAI } from '@langfuse/openai';
+import OpenAI from 'openai';
+
+// Wraps OpenAI client for automatic trace capture
+const openai = observeOpenAI(new OpenAI(), {
+  langfuse,
+  generationName: 'coaia-generation',
+});
+
+// Every call is automatically traced
+const response = await openai.chat.completions.create({
+  model: 'gpt-5.4',
+  messages: [{ role: 'user', content: 'Analyze this chart...' }],
+});
+```
+
+### Prompt Management
+
+```typescript
+// Fetch versioned prompts from Langfuse
+const prompt = await langfuse.getPrompt('pde-decompose-system');
+const compiled = prompt.compile({ context: 'structural tension chart' });
+```
+
+### Scoring (replacing cofuse.py create_score, apply_score_to_trace)
+
+```typescript
+async function scoreTrace(traceId: string, scores: Record<string, number>) {
+  for (const [name, value] of Object.entries(scores)) {
+    langfuse.score({
+      traceId,
+      name,
+      value,
+      comment: `MMOT evaluation: ${name}`,
+    });
+  }
+  await langfuse.flushAsync();
+}
+```
+
+## Integration Plan
+
+1. **Core module:** `src/langfuse/client.ts` — singleton Langfuse instance from config
+2. **Session tracing:** `src/langfuse/session.ts` — trace lifecycle for agent sessions (replaces cofuse.py)
+3. **OpenAI wrapper:** `src/langfuse/openai.ts` — `observeOpenAI` integration for automatic tracing
+4. **Scoring:** `src/langfuse/scoring.ts` — MMOT evaluation scoring
+5. **Prompt management:** `src/langfuse/prompts.ts` — versioned prompt fetching
+6. **Pipeline integration:** `src/pipeline/traced-step.ts` — auto-trace pipeline template execution
+
+### When to Fall Back to REST
+
+Keep a thin REST utility for edge cases:
+- Langfuse endpoints not yet covered by SDK v4
+- Direct database queries for custom dashboards
+- Webhook payload verification
+
+```typescript
+// Escape hatch for REST-only endpoints
+async function langfuseRest(path: string, method = 'GET', body?: object) {
+  const config = loadConfig();
+  const auth = Buffer.from(`${config.langfusePublicKey}:${config.langfuseSecretKey}`).toString('base64');
+  return fetch(`${config.langfuseBaseUrl}/api/public${path}`, {
+    method,
+    headers: { Authorization: `Basic ${auth}`, 'Content-Type': 'application/json' },
+    body: body ? JSON.stringify(body) : undefined,
+  });
+}
+```
+
+## Version & Ecosystem
+
+| Metric | Value |
+|--------|-------|
+| Current version | v4.x (rewritten Aug 2025) |
+| Packages | `langfuse`, `@langfuse/core`, `@langfuse/tracing`, `@langfuse/openai` |
+| Tracing standard | OpenTelemetry native |
+| Node.js compat | ≥20 |
+| TypeScript | Full native types |
+| Bundle | Modular tree-shakeable |
+| Integrations | OpenAI, LangChain, Vercel AI SDK |
+| MCP | Hosted MCP server for prompt management |
+| License | MIT |
+
+## References
+
+- npm: https://www.npmjs.com/package/langfuse
+- GitHub: https://github.com/langfuse/langfuse-js
+- Docs: https://langfuse.com/docs/sdk/typescript
+- Changelog: https://langfuse.com/changelog
+- DeepWiki architecture: https://deepwiki.com/langfuse/langfuse-js

package/articles/technical/mcp-sdk-typescript.md

@@ -0,0 +1,291 @@
+# @modelcontextprotocol/sdk: Technical Assessment for CoAiA.js
+
+> Package selection brief — MCP server and client framework for exposing CoAiA tools, resources, and prompts to LLM agents
+
+## Summary & Recommendation
+
+**Use `@modelcontextprotocol/sdk` v1.x** (currently 1.27.x). This is the official Tier-1 TypeScript SDK for the Model Context Protocol. It's already used by coaia-pde, coaia-planning, and coaia-narrative. For coaiajs, we consolidate all three MCP servers into a single unified server with Zod-validated tools. Stick with v1 until v2 reaches stable (expected Q2 2026).
+
+**Pin:** `"@modelcontextprotocol/sdk": "^1.25.0"` + `"zod": "^4.0.0"` (peer dependency)
+
+## What We're Replacing
+
+Three separate MCP servers each with their own Server instance:
+
+### coaia-pde (Server + raw JSON schemas)
+```typescript
+import { Server } from '@modelcontextprotocol/sdk/server/index.js';
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import { CallToolRequestSchema, ListToolsRequestSchema } from '@modelcontextprotocol/sdk/types.js';
+
+const server = new Server(
+  { name: 'coaia-pde', version: '1.0.0' },
+  { capabilities: { tools: {} } }
+);
+server.setRequestHandler(ListToolsRequestSchema, async () => ({ tools: TOOLS }));
+server.setRequestHandler(CallToolRequestSchema, async (request) => {
+  const { name, arguments: args } = request.params;
+  switch(name) { case 'import_pde_decomposition': /* ... */ }
+});
+```
+
+### coaia-planning (Server + minimist config)
+```typescript
+const args = minimist(process.argv.slice(2));
+const PLANS_DIR = args['plans-dir'] || process.env.COAIA_PLANS_DIR;
+server.setRequestHandler(CallToolRequestSchema, async (request) => {
+  switch (name) {
+    case 'parse_plan_structural': /* ... */
+    case 'plan_to_stc': /* ... */
+  }
+});
+```
+
+### coaia-narrative (Server + custom validation.ts)
+```typescript
+// Uses custom validation.ts for argument checking before processing
+const { valid, error } = validate(args, EntityArraySchema);
+if (!valid) return errorResponse(error);
+```
+
+All three use the **low-level** `Server` class with raw `setRequestHandler` and manual JSON schema definitions. The SDK's higher-level `McpServer` class with Zod eliminates this boilerplate.
+
+## Options Compared
+
+| Feature | McpServer (high-level) | Server (low-level) | Custom HTTP |
+|---------|----------------------|-------------------|-------------|
+| Tool definition | `server.tool(name, schema, handler)` | Manual `setRequestHandler` + switch | Manual routing |
+| Schema validation | Zod automatic | Manual JSON Schema | Manual |
+| Type inference | Full from Zod schemas | Manual casting | None |
+| Resource support | `server.resource()` | Manual handler | Manual |
+| Prompt templates | `server.prompt()` | Manual handler | N/A |
+| Transport | Stdio, HTTP, SSE built-in | Stdio, HTTP, SSE built-in | Custom |
+| Code per tool | ~10 lines | ~25 lines | ~50 lines |
+| Used by our projects | New for coaiajs | coaia-pde, coaia-planning, coaia-narrative | N/A |
+
+## API Overview
+
+### Unified MCP Server (High-Level API)
+
+```typescript
+// mcp/server.ts — single unified MCP server for coaiajs
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import { z } from 'zod';
+
+const server = new McpServer({
+  name: 'coaiajs',
+  version: '1.0.0',
+});
+
+// --- NARRATIVE TOOLS ---
+
+server.tool(
+  'create_structural_tension_chart',
+  'Create a new structural tension chart with desired outcome and current reality',
+  {
+    desiredOutcome: z.string().min(1).describe('What you want to CREATE'),
+    currentReality: z.string().min(1).describe('Factual assessment — never "ready to begin"'),
+    dueDate: z.string().datetime().optional().describe('ISO 8601 target date'),
+    actionSteps: z.array(z.string()).optional().describe('Initial action steps'),
+  },
+  async ({ desiredOutcome, currentReality, dueDate, actionSteps }) => {
+    const chart = await createChart({ desiredOutcome, currentReality, dueDate, actionSteps });
+    return { content: [{ type: 'text', text: JSON.stringify(chart) }] };
+  }
+);
+
+server.tool(
+  'mark_action_complete',
+  'Mark an action step as completed',
+  {
+    actionStepName: z.string().min(1).describe('Name of the completed action step'),
+  },
+  async ({ actionStepName }) => {
+    const result = await markComplete(actionStepName);
+    return { content: [{ type: 'text', text: JSON.stringify(result) }] };
+  }
+);
+
+// --- PDE TOOLS ---
+
+server.tool(
+  'pde_decompose',
+  'Decompose a complex prompt into structured facets',
+  {
+    prompt: z.string().min(1).describe('The complex prompt to decompose'),
+    extractImplicit: z.boolean().default(true).describe('Extract implicit intents'),
+    mapDependencies: z.boolean().default(true).describe('Map inter-facet dependencies'),
+  },
+  async ({ prompt, extractImplicit, mapDependencies }) => {
+    const result = await decompose(prompt, { extractImplicit, mapDependencies });
+    return { content: [{ type: 'text', text: JSON.stringify(result) }] };
+  }
+);
+
+// --- PLANNING TOOLS ---
+
+server.tool(
+  'parse_plan_structural',
+  'Parse a plan into structural tension format',
+  {
+    planPath: z.string().optional().describe('Path to plan file'),
+    planContent: z.string().optional().describe('Raw plan content'),
+  },
+  async ({ planPath, planContent }) => {
+    const parsed = planPath ? await parsePlan(planPath) : parsePlanContent(planContent!);
+    return { content: [{ type: 'text', text: JSON.stringify(parsed) }] };
+  }
+);
+```
+
+### Resources (Read-Only Data)
+
+```typescript
+// Expose chart data as MCP resources
+server.resource(
+  'charts',
+  'chart://list',
+  async (uri) => {
+    const charts = await listActiveCharts();
+    return {
+      contents: [{
+        uri: uri.href,
+        mimeType: 'application/json',
+        text: JSON.stringify(charts),
+      }],
+    };
+  }
+);
+
+// Dynamic resource with URI template
+server.resource(
+  'chart-detail',
+  'chart://{chartId}',
+  async (uri, { chartId }) => {
+    const chart = await getChart(chartId);
+    return {
+      contents: [{
+        uri: uri.href,
+        mimeType: 'application/json',
+        text: JSON.stringify(chart),
+      }],
+    };
+  }
+);
+```
+
+### Prompt Templates
+
+```typescript
+server.prompt(
+  'mmot-evaluation',
+  'MMOT self-evaluation prompt for structural tension chart',
+  {
+    chartId: z.string().describe('Chart ID to evaluate'),
+    direction: z.enum(['South', 'East', 'West', 'North']).optional(),
+  },
+  async ({ chartId, direction }) => {
+    const chart = await getChart(chartId);
+    return {
+      messages: [{
+        role: 'user',
+        content: {
+          type: 'text',
+          text: `Evaluate chart "${chart.desiredOutcome}" from ${direction ?? 'all'} direction(s)...`,
+        },
+      }],
+    };
+  }
+);
+```
+
+### Transport & Startup
+
+```typescript
+// Stdio transport (default for CLI agent integration)
+async function main() {
+  const transport = new StdioServerTransport();
+  await server.connect(transport);
+  console.error('coaiajs MCP server running on stdio');
+}
+
+main().catch(console.error);
+```
+
+### Low-Level API (when needed)
+
+For advanced scenarios (custom transports, middleware, session state), the low-level `Server` class remains available:
+
+```typescript
+import { Server } from '@modelcontextprotocol/sdk/server/index.js';
+
+const lowLevelServer = new Server(
+  { name: 'coaiajs-advanced', version: '1.0.0' },
+  { capabilities: { tools: {}, resources: {}, prompts: {} } }
+);
+
+// Custom request handler with full control
+lowLevelServer.setRequestHandler(CallToolRequestSchema, async (request) => {
+  // Pre-processing middleware, custom logging, etc.
+});
+```
+
+## Integration Plan
+
+1. **Unified server:** `mcp/server.ts` — single McpServer combining all tools
+2. **Tool modules:** `mcp/tools/` directory
+   - `narrative.ts` — chart CRUD, action steps, MMOT
+   - `pde.ts` — prompt decomposition tools
+   - `planning.ts` — plan parsing, STC conversion
+   - `pipeline.ts` — pipeline template execution
+   - `langfuse.ts` — trace/score management
+3. **Resources:** `mcp/resources/` — chart data, session data, template listings
+4. **Prompts:** `mcp/prompts/` — MMOT evaluation, PDE system prompts
+5. **Bin entry:** `"coaiajs-mcp": "./dist/mcp/server.js"` in package.json
+6. **Migration:** Gradually absorb coaia-pde, coaia-planning, coaia-narrative tools
+
+### Tool Registration Pattern
+
+```typescript
+// mcp/tools/index.ts — register all tool modules
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+
+export function registerAllTools(server: McpServer) {
+  registerNarrativeTools(server);
+  registerPdeTools(server);
+  registerPlanningTools(server);
+  registerPipelineTools(server);
+  registerLangfuseTools(server);
+}
+```
+
+## Version & Ecosystem
+
+| Metric | Value |
+|--------|-------|
+| Current version | 1.27.1 (Feb 2026) |
+| V2 status | Pre-alpha on main branch, stable Q1-Q2 2026 |
+| Peer dependency | zod ≥3.25 |
+| Transports | stdio, Streamable HTTP, SSE |
+| Node.js compat | ≥18 (we target ≥20) |
+| TypeScript | Native, first-class |
+| Protocol spec | modelcontextprotocol.io |
+| Weekly downloads | Growing rapidly (protocol adoption) |
+| License | MIT |
+
+## V1 → V2 Migration Notes
+
+V2 (pre-alpha) brings breaking changes. Our plan:
+- Build on V1 now (`^1.25.0`)
+- V1 will receive security updates for 6+ months post-V2 release
+- When V2 stabilizes, migrate — the high-level McpServer API is expected to remain similar
+
+## References
+
+- npm: https://www.npmjs.com/package/@modelcontextprotocol/sdk
+- GitHub: https://github.com/modelcontextprotocol/typescript-sdk
+- Protocol docs: https://modelcontextprotocol.io/docs/sdk
+- API reference: https://markaicode.com/mcp-typescript-sdk-api-reference/
+- V2 docs: https://ts.sdk.modelcontextprotocol.io/v2/
+- Tutorial: https://dev.to/1xapi/how-to-build-mcp-servers-in-nodejs-for-ai-agents-2026-guide-fdi