coaiajs 0.1.0

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

package/articles/technical/octokit-github-api.md

@@ -0,0 +1,293 @@
+# @octokit/rest: Technical Assessment for CoAiA.js
+
+> Package selection brief — GitHub REST API client replacing coaiapy's raw requests in cogh.py
+
+## Summary & Recommendation
+
+**Use `@octokit/rest` v22.x** (currently 22.0.1). Octokit is the official GitHub-maintained JavaScript client for the GitHub REST API. It replaces coaiapy's `cogh.py` which manually constructs HTTP requests with auth headers. Octokit provides typed methods for every GitHub endpoint, automatic pagination, built-in authentication, and rate limit handling.
+
+**Pin:** `"@octokit/rest": "^22.0.0"`
+
+## What We're Replacing
+
+Coaiapy's `cogh.py` uses raw HTTP requests:
+
+```python
+# coaiapy/cogh.py — manual GitHub API
+import requests
+import os
+
+def _get_github_headers():
+    config = read_config()
+    token = config.get("github", {}).get("api_token") or os.getenv("GH_TOKEN")
+    return {
+        "Authorization": f"Bearer {token}",
+        "Accept": "application/vnd.github.v3+json"
+    }
+
+def list_issues(owner, repo):
+    headers = _get_github_headers()
+    response = requests.get(
+        f"https://api.github.com/repos/{owner}/{repo}/issues",
+        headers=headers
+    )
+    return response.json()
+
+def get_issue(owner, repo, issue_number):
+    headers = _get_github_headers()
+    response = requests.get(
+        f"https://api.github.com/repos/{owner}/{repo}/issues/{issue_number}",
+        headers=headers
+    )
+    return response.json()
+```
+
+Issues: no pagination handling, no rate limit awareness, no type safety, manual URL construction, no retry logic.
+
+## Options Compared
+
+| Feature | @octokit/rest v22 | Raw fetch/requests | graphql (@octokit/graphql) |
+|---------|-------------------|-------------------|--------------------------|
+| API coverage | All REST endpoints typed | Manual per endpoint | GraphQL (different paradigm) |
+| Authentication | Token, App, OAuth, Action | Manual headers | Same as octokit |
+| Pagination | `octokit.paginate()` automatic | Manual `Link` header parsing | Cursor-based (manual) |
+| Rate limiting | Built-in retry plugin | Manual `X-RateLimit-*` handling | Same as octokit |
+| TypeScript | Full types for every endpoint | Manual interfaces | Partial |
+| Request/response hooks | Plugin system | Manual interceptors | Plugin system |
+| Bundle size | ~150KB | 0 | ~50KB |
+| Maintenance | GitHub-maintained official | N/A | GitHub-maintained official |
+
+## API Overview
+
+### Client Setup
+
+```typescript
+import { Octokit } from '@octokit/rest';
+import { loadConfig } from '../config.js';
+
+const config = loadConfig();
+
+const octokit = new Octokit({
+  auth: config.githubToken ?? process.env.GH_TOKEN,
+  userAgent: 'coaiajs/1.0.0',
+});
+```
+
+### Issues API (replacing cogh.py)
+
+```typescript
+// List issues (replaces cogh.list_issues)
+async function listIssues(owner: string, repo: string, options?: {
+  state?: 'open' | 'closed' | 'all';
+  labels?: string[];
+  per_page?: number;
+}) {
+  const { data } = await octokit.rest.issues.listForRepo({
+    owner,
+    repo,
+    state: options?.state ?? 'open',
+    labels: options?.labels?.join(','),
+    per_page: options?.per_page ?? 30,
+  });
+  return data;
+}
+
+// Get single issue (replaces cogh.get_issue)
+async function getIssue(owner: string, repo: string, issueNumber: number) {
+  const { data } = await octokit.rest.issues.get({
+    owner,
+    repo,
+    issue_number: issueNumber,
+  });
+  return data;
+}
+
+// Create issue
+async function createIssue(owner: string, repo: string, title: string, body: string, labels?: string[]) {
+  const { data } = await octokit.rest.issues.create({
+    owner,
+    repo,
+    title,
+    body,
+    labels,
+  });
+  return data;
+}
+
+// Add comment to issue
+async function commentOnIssue(owner: string, repo: string, issueNumber: number, body: string) {
+  const { data } = await octokit.rest.issues.createComment({
+    owner,
+    repo,
+    issue_number: issueNumber,
+    body,
+  });
+  return data;
+}
+```
+
+### Automatic Pagination
+
+```typescript
+// Fetch ALL issues across all pages
+async function listAllIssues(owner: string, repo: string) {
+  const issues = await octokit.paginate(octokit.rest.issues.listForRepo, {
+    owner,
+    repo,
+    state: 'all',
+    per_page: 100,
+  });
+  return issues; // All pages concatenated
+}
+```
+
+### Session Management (Miadi webhook pattern)
+
+```typescript
+// Create issue for agent session tracking
+async function createSessionIssue(
+  owner: string,
+  repo: string,
+  sessionId: string,
+  metadata: Record<string, string>
+) {
+  const body = [
+    `## Agent Session: ${sessionId}`,
+    '',
+    '| Key | Value |',
+    '|-----|-------|',
+    ...Object.entries(metadata).map(([k, v]) => `| ${k} | ${v} |`),
+  ].join('\n');
+
+  return createIssue(owner, repo, `Session: ${sessionId}`, body, ['agent-session']);
+}
+
+// Update session with results
+async function updateSessionIssue(
+  owner: string,
+  repo: string,
+  issueNumber: number,
+  results: string
+) {
+  await commentOnIssue(owner, repo, issueNumber, results);
+  
+  // Close when session completes
+  await octokit.rest.issues.update({
+    owner,
+    repo,
+    issue_number: issueNumber,
+    state: 'closed',
+  });
+}
+```
+
+### Repository Operations
+
+```typescript
+// Get file contents
+async function getFileContent(owner: string, repo: string, path: string, ref?: string) {
+  const { data } = await octokit.rest.repos.getContent({
+    owner,
+    repo,
+    path,
+    ref,
+  });
+  if ('content' in data) {
+    return Buffer.from(data.content, 'base64').toString('utf-8');
+  }
+  throw new Error(`${path} is not a file`);
+}
+
+// List commits
+async function listRecentCommits(owner: string, repo: string, count = 10) {
+  const { data } = await octokit.rest.repos.listCommits({
+    owner,
+    repo,
+    per_page: count,
+  });
+  return data.map(c => ({
+    sha: c.sha.slice(0, 7),
+    message: c.commit.message.split('\n')[0],
+    author: c.commit.author?.name,
+    date: c.commit.author?.date,
+  }));
+}
+```
+
+### Authentication Patterns
+
+```typescript
+// Pattern 1: Personal Access Token (default)
+const octokit = new Octokit({ auth: process.env.GH_TOKEN });
+
+// Pattern 2: GitHub Actions token
+const octokit = new Octokit({ auth: process.env.GITHUB_TOKEN });
+
+// Pattern 3: GitHub App (for Miadi webhook integration)
+import { createAppAuth } from '@octokit/auth-app';
+
+const octokit = new Octokit({
+  authStrategy: createAppAuth,
+  auth: {
+    appId: config.githubAppId,
+    privateKey: config.githubPrivateKey,
+    installationId: config.githubInstallationId,
+  },
+});
+```
+
+### Formatting (replacing cogh.format_issues_table)
+
+```typescript
+function formatIssuesTable(issues: Awaited<ReturnType<typeof listIssues>>): string {
+  const header = '| # | Title | State | Labels | Updated |';
+  const separator = '|---|-------|-------|--------|---------|';
+  const rows = issues.map(i => 
+    `| ${i.number} | ${i.title} | ${i.state} | ${i.labels.map(l => 
+      typeof l === 'string' ? l : l.name).join(', ')} | ${i.updated_at?.slice(0, 10)} |`
+  );
+  return [header, separator, ...rows].join('\n');
+}
+```
+
+## Integration Plan
+
+1. **Core client:** `src/github/client.ts` — Octokit singleton from config
+2. **Issues module:** `src/github/issues.ts` — CRUD + pagination (replaces cogh.py)
+3. **Session tracking:** `src/github/sessions.ts` — issue-based session management
+4. **Repository module:** `src/github/repos.ts` — file content, commits
+5. **CLI command:** `src/commands/gh.ts` — Commander subcommand for GitHub ops
+6. **MCP tool:** `mcp/tools/github.ts` — GitHub operations as agent tools
+7. **Auth:** Support PAT, Actions token, and GitHub App auth
+
+## Version & Ecosystem
+
+| Metric | Value |
+|--------|-------|
+| Current version | 22.0.1 (Feb 2026) |
+| Weekly downloads | ~10M+ |
+| TypeScript | Full native types for every endpoint |
+| Node.js compat | ≥20 (v22 dropped Node 18) |
+| Authentication | PAT, OAuth, App, Actions |
+| Pagination | Built-in `octokit.paginate()` |
+| Rate limiting | Plugin-based retry |
+| Maintained by | GitHub (official) |
+| License | MIT |
+
+### Ecosystem Packages
+
+| Package | Purpose | When to Use |
+|---------|---------|-------------|
+| `@octokit/rest` | REST API client | Primary — all REST operations |
+| `@octokit/graphql` | GraphQL API | Complex queries (PR reviews, nested data) |
+| `@octokit/auth-app` | GitHub App auth | Miadi webhook integration |
+| `@octokit/webhooks` | Webhook handling | Receiving GitHub webhooks |
+| `@octokit/plugin-paginate-rest` | Pagination | Included in @octokit/rest |
+
+## References
+
+- npm: https://www.npmjs.com/package/@octokit/rest
+- GitHub: https://github.com/octokit/rest.js
+- Docs: https://octokit.github.io/rest.js/v22/
+- Auth patterns: https://github.com/octokit/auth-app.js
+- Releases: https://github.com/octokit/rest.js/releases