stellar-agent 0.2.0 → 0.3.0

package/tools/mcp-server/server.js

@@ -0,0 +1,281 @@
+#!/usr/bin/env node
+/**
+ * Stellar Agent — MCP Server
+ *
+ * Exposes the stellar-agent skill catalog and agent personas to any
+ * MCP-compatible client (Claude Desktop, Cline, Continue, Zed, etc.)
+ * over stdio.
+ *
+ * Hand-rolled JSON-RPC 2.0 implementation to avoid an SDK dependency —
+ * keeps the published package lean.
+ *
+ * Tools exposed:
+ *   - list_agents                       → roster of all 8 agents
+ *   - list_skills(phase?, agent?)       → catalog of skills
+ *   - get_skill(name)                   → SKILL.md content
+ *   - get_agent(name)                   → persona block + menu
+ *
+ * Run: `stellar-agent mcp` or `node tools/mcp-server/server.js`
+ */
+
+const fsp = require('node:fs/promises');
+const fs = require('node:fs');
+const path = require('node:path');
+const readline = require('node:readline');
+const yaml = require('yaml');
+
+const REPO_ROOT = path.join(__dirname, '..', '..');
+const SRC_DIR = path.join(REPO_ROOT, 'src');
+const STELLAR_SKILLS_DIR = path.join(SRC_DIR, 'stellar-skills');
+const CORE_SKILLS_DIR = path.join(SRC_DIR, 'core-skills');
+const PROTOCOL_VERSION = '2024-11-05';
+const SERVER_INFO = { name: 'stellar-agent', version: require('../../package.json').version };
+
+// ---------- Catalog loaders ----------
+
+async function loadAgents() {
+  const moduleYaml = await fsp.readFile(path.join(STELLAR_SKILLS_DIR, 'module.yaml'), 'utf8');
+  const data = yaml.parse(moduleYaml);
+  return data.agents || [];
+}
+
+async function loadSkills({ phase, agent } = {}) {
+  const skills = [];
+
+  // Walk core-skills/*/SKILL.md
+  for (const entry of await fsp.readdir(CORE_SKILLS_DIR, { withFileTypes: true })) {
+    if (!entry.isDirectory()) continue;
+    const skillPath = path.join(CORE_SKILLS_DIR, entry.name, 'SKILL.md');
+    if (!fs.existsSync(skillPath)) continue;
+    skills.push(await readSkillFrontmatter(skillPath, 'core', entry.name));
+  }
+
+  // Walk stellar-skills/<phase>/<skill>/SKILL.md
+  for (const phaseEntry of await fsp.readdir(STELLAR_SKILLS_DIR, { withFileTypes: true })) {
+    if (!phaseEntry.isDirectory()) continue;
+    const phaseDir = path.join(STELLAR_SKILLS_DIR, phaseEntry.name);
+    for (const skillEntry of await fsp.readdir(phaseDir, { withFileTypes: true })) {
+      if (!skillEntry.isDirectory()) continue;
+      const skillPath = path.join(phaseDir, skillEntry.name, 'SKILL.md');
+      if (!fs.existsSync(skillPath)) continue;
+      skills.push(await readSkillFrontmatter(skillPath, phaseEntry.name, skillEntry.name));
+    }
+  }
+
+  let filtered = skills;
+  if (phase) filtered = filtered.filter((s) => s.phase === phase);
+  if (agent) filtered = filtered.filter((s) => (s.agent || '').toLowerCase() === agent.toLowerCase());
+  return filtered;
+}
+
+async function readSkillFrontmatter(filePath, phase, dirname) {
+  const raw = await fsp.readFile(filePath, 'utf8');
+  const frontmatter = parseFrontmatter(raw);
+  // Detect agent-persona skills by naming convention: stellar-agent-*
+  const isAgent = dirname.startsWith('stellar-agent-');
+  return {
+    name: frontmatter.name || dirname,
+    description: frontmatter.description || '',
+    phase,
+    type: isAgent ? 'agent' : 'skill',
+    path: path.relative(REPO_ROOT, filePath),
+  };
+}
+
+function parseFrontmatter(text) {
+  const match = text.match(/^---\n([\s\S]*?)\n---/);
+  if (!match) return {};
+  const out = {};
+  for (const line of match[1].split('\n')) {
+    const m = line.match(/^([a-zA-Z_]+):\s*['"]?(.*?)['"]?$/);
+    if (m) out[m[1]] = m[2];
+  }
+  return out;
+}
+
+async function getSkillContent(name) {
+  // Look in core-skills
+  const corePath = path.join(CORE_SKILLS_DIR, name, 'SKILL.md');
+  if (fs.existsSync(corePath)) return fsp.readFile(corePath, 'utf8');
+  // Look in stellar-skills/<phase>/<name>
+  for (const phaseEntry of await fsp.readdir(STELLAR_SKILLS_DIR, { withFileTypes: true })) {
+    if (!phaseEntry.isDirectory()) continue;
+    const candidate = path.join(STELLAR_SKILLS_DIR, phaseEntry.name, name, 'SKILL.md');
+    if (fs.existsSync(candidate)) return fsp.readFile(candidate, 'utf8');
+  }
+  throw new Error(`Skill not found: ${name}`);
+}
+
+async function getAgentDetail(name) {
+  const agents = await loadAgents();
+  const agent = agents.find(
+    (a) =>
+      a.code === name ||
+      a.name?.toLowerCase() === name.toLowerCase() ||
+      a.code === `stellar-agent-${name.toLowerCase()}`
+  );
+  if (!agent) throw new Error(`Agent not found: ${name}`);
+
+  // Resolve agent's SKILL.md + customize.toml for menu
+  let menu = [];
+  let persona = null;
+  for (const phaseEntry of await fsp.readdir(STELLAR_SKILLS_DIR, { withFileTypes: true })) {
+    if (!phaseEntry.isDirectory()) continue;
+    const dir = path.join(STELLAR_SKILLS_DIR, phaseEntry.name, agent.code);
+    if (!fs.existsSync(dir)) continue;
+    const skillPath = path.join(dir, 'SKILL.md');
+    const customizePath = path.join(dir, 'customize.toml');
+    if (fs.existsSync(skillPath)) persona = await fsp.readFile(skillPath, 'utf8');
+    if (fs.existsSync(customizePath)) {
+      const tomlText = await fsp.readFile(customizePath, 'utf8');
+      menu = parseAgentMenu(tomlText);
+    }
+    break;
+  }
+  return { agent, persona, menu };
+}
+
+function parseAgentMenu(toml) {
+  // Lightweight extractor for [[agent.menu]] blocks
+  const blocks = toml.split(/\[\[agent\.menu\]\]/).slice(1);
+  return blocks.map((block) => {
+    const lines = block.split('\n');
+    const entry = {};
+    for (const line of lines) {
+      const m = line.match(/^\s*(code|description|skill)\s*=\s*"(.*)"\s*$/);
+      if (m) entry[m[1]] = m[2];
+    }
+    return entry;
+  });
+}
+
+// ---------- MCP protocol ----------
+
+const TOOLS = [
+  {
+    name: 'list_agents',
+    description: 'List all Stellar Agent team members with their handle, role, icon, and phase.',
+    inputSchema: { type: 'object', properties: {}, additionalProperties: false },
+  },
+  {
+    name: 'list_skills',
+    description:
+      'List available skills in the Stellar Agent catalog. Optionally filter by phase (1-analysis, 2-planning, 3-architecture, 4-implementation, 5-mentorship, core).',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        phase: {
+          type: 'string',
+          description: 'Optional phase filter — e.g. "4-implementation" or "core".',
+        },
+      },
+      additionalProperties: false,
+    },
+  },
+  {
+    name: 'get_skill',
+    description: 'Return the full SKILL.md content for a named skill (e.g. "stellar-write-contract").',
+    inputSchema: {
+      type: 'object',
+      properties: { name: { type: 'string', description: 'Skill name (kebab-case).' } },
+      required: ['name'],
+      additionalProperties: false,
+    },
+  },
+  {
+    name: 'get_agent',
+    description:
+      'Return the persona, principles, and skill menu for a specific Stellar Agent (e.g. "sol", "pera").',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        name: { type: 'string', description: 'Agent name or handle (e.g. "sol" or "stellar-agent-developer").' },
+      },
+      required: ['name'],
+      additionalProperties: false,
+    },
+  },
+];
+
+function jsonResponse(id, result) {
+  return JSON.stringify({ jsonrpc: '2.0', id, result });
+}
+
+function jsonError(id, code, message) {
+  return JSON.stringify({ jsonrpc: '2.0', id, error: { code, message } });
+}
+
+async function handleRequest(req) {
+  const { id, method, params } = req;
+
+  if (method === 'initialize') {
+    return jsonResponse(id, {
+      protocolVersion: PROTOCOL_VERSION,
+      capabilities: { tools: {} },
+      serverInfo: SERVER_INFO,
+    });
+  }
+
+  if (method === 'tools/list') {
+    return jsonResponse(id, { tools: TOOLS });
+  }
+
+  if (method === 'tools/call') {
+    const { name, arguments: args = {} } = params || {};
+    try {
+      let payload;
+      if (name === 'list_agents') {
+        payload = await loadAgents();
+      } else if (name === 'list_skills') {
+        payload = await loadSkills(args);
+      } else if (name === 'get_skill') {
+        if (!args.name) throw new Error('Missing required argument: name');
+        payload = await getSkillContent(args.name);
+      } else if (name === 'get_agent') {
+        if (!args.name) throw new Error('Missing required argument: name');
+        payload = await getAgentDetail(args.name);
+      } else {
+        return jsonError(id, -32601, `Unknown tool: ${name}`);
+      }
+
+      const text = typeof payload === 'string' ? payload : JSON.stringify(payload, null, 2);
+      return jsonResponse(id, { content: [{ type: 'text', text }] });
+    } catch (err) {
+      return jsonResponse(id, {
+        content: [{ type: 'text', text: `Error: ${err.message}` }],
+        isError: true,
+      });
+    }
+  }
+
+  if (method === 'notifications/initialized') {
+    return null; // no response for notifications
+  }
+
+  return jsonError(id, -32601, `Method not found: ${method}`);
+}
+
+// ---------- Stdio loop ----------
+
+async function main() {
+  const rl = readline.createInterface({ input: process.stdin });
+  rl.on('line', async (line) => {
+    if (!line.trim()) return;
+    let req;
+    try {
+      req = JSON.parse(line);
+    } catch (err) {
+      process.stdout.write(jsonError(null, -32700, 'Parse error') + '\n');
+      return;
+    }
+    const response = await handleRequest(req);
+    if (response) process.stdout.write(response + '\n');
+  });
+
+  rl.on('close', () => process.exit(0));
+}
+
+main().catch((err) => {
+  console.error('MCP server fatal error:', err);
+  process.exit(1);
+});