stellar-agent 0.1.0 → 0.3.0

package/src/stellar-skills/5-mentorship/stellar-track-recommendation/SKILL.md

@@ -0,0 +1,97 @@
+---
+name: stellar-track-recommendation
+description: 'Match a hackathon idea to the right Stellar/Soroban track and surface the judging rubric for that track. Use when the user is undecided between tracks, wants to know which track fits their idea best, or needs to read the rubric before building.'
+---
+
+# Track Recommendation
+
+## Purpose
+
+Pick the right hackathon track for the idea. The wrong track punishes the team twice — judges score against criteria the build wasn't optimized for, and the team misses the rubric that would've shaped a better build.
+
+## On Activation
+
+Load `{planning_artifacts}/hackathon-brief.md` if it exists. If not, recommend running `IS` (Idea Scoping) first.
+
+If a hackathon URL was provided to Pera on greeting, fetch it now and read the official track list and rubrics. Treat the live page as source of truth — overrides anything below.
+
+## Workflow
+
+### Step 1: Identify Candidate Tracks
+
+Match the idea against the Stellar hackathon track families:
+
+| Track | Best fits | Stellar/Soroban primitive | Judging weight |
+|---|---|---|---|
+| **DeFi** | Lending, AMM, yield, perp/swap, stablecoin mech | Soroban contracts, AMM pools, trustlines | Technical depth · Composability · TVL potential |
+| **Payments** | Cross-border, remittance, micropayments, payroll | Classic Stellar payments, anchors, path payments | UX · Cost per tx · Anchor / SEP integration |
+| **Identity / SEP-10** | KYC, attestation, reputation, gated access | SEP-10 auth, Soroban storage for attestations | Privacy · SEP compliance · Real-world fit |
+| **Gaming / NFT** | On-chain assets, in-game economy, collectibles | Custom assets, Soroban inventory contracts | Player retention · Creative use of Soroban |
+| **RWA / Tokenization** | Real estate, invoices, commodities, carbon | Custom assets + Soroban escrow + oracles | Legal viability · Oracle design · Trust model |
+| **Infra / DevTools** | SDKs, dashboards, oracles, indexers | Anything that helps other devs ship on Stellar | Developer adoption · Reusability |
+| **Open / Other** | Idea doesn't fit above | Anything | Innovation · Demo · Business potential |
+
+### Step 2: Score the Idea Against Each Candidate
+
+For each candidate track, produce a 3-line block:
+
+```
+<Track>
+Fit: <high | medium | low> — <one-line reason>
+Win condition: <what would the judges score highly>
+Risk: <what the judges will challenge>
+```
+
+If two tracks score `high`, prefer the one with:
+- Smaller judging field (less competition)
+- Rubric the build naturally aligns to without rework
+
+### Step 3: Recommend
+
+Output:
+
+```markdown
+## Track recommendation
+
+**Primary:** <track>
+**Why:** <one sentence — the strongest rubric alignment>
+**Risk to mitigate:** <what to harden before submission>
+
+**Secondary (if primary doesn't fit at submission):** <track>
+```
+
+### Step 4: Pull the Rubric
+
+If the hackathon URL is known, extract the official rubric from the page. Otherwise use the generic Stellar judging rubric:
+
+| Criterion | Default weight | Notes |
+|---|---|---|
+| Innovation | 25% | "Have we seen this before on Stellar?" |
+| Technical implementation | 25% | Soroban depth, code quality, test coverage |
+| Business / impact | 25% | Who pays, how big, distribution path |
+| Demo quality | 25% | Recording, narration, on-chain proof |
+
+Append to `{planning_artifacts}/hackathon-brief.md` as a `## Track + rubric` section.
+
+### Step 5: Confirm
+
+Ask the user: *"Locking in `<track>` — proceed?"*
+
+If yes, suggest `MV` next.
+If no, present the secondary or ask what's missing.
+
+## Common mistakes
+
+- **Picking DeFi by default.** DeFi is the most crowded track at most Stellar hackathons. A "DeFi-lite" idea in Payments or Identity often wins more easily.
+- **Picking a track because the team likes it.** Track choice is about rubric fit, not preference.
+- **Ignoring the official rubric.** Always pull the actual hackathon's rubric over generic priors. Hackathons weight criteria differently.
+- **Multi-track submissions.** Most Stellar hackathons only allow one track. Picking two splits attention.
+
+## Output
+
+Updates `{planning_artifacts}/hackathon-brief.md` with the chosen track and the rubric the build must align to.
+
+## Next Steps
+
+- `stellar-mvp-definition` (MV) — cut the feature list against the chosen rubric
+- `stellar-judging-criteria` (JC) — when the MVP is locked, map it to the rubric line-by-line

package/src/stellar-skills/module-help.csv

@@ -3,11 +3,13 @@ Stellar,_meta,,,,,,,,,false,https://github.com/tolgazorlu/stellar-agent#readme,
 Stellar,stellar-analytics,Analytics Setup,AN,Set up dbt blockchain analytics for Stellar network data and tokenomics reporting.,,,1-analysis,,,false,{project_knowledge},dbt models
 Stellar,stellar-market-research,Market Research,MR,DeFi landscape competitive analysis and Stellar ecosystem research.,,,1-analysis,,,false,{planning_artifacts},research document
 Stellar,stellar-domain-research,Domain Research,DR,Stellar protocol deep dive — tokenomics regulatory landscape and use case research.,,,1-analysis,,,false,{planning_artifacts},research document
+Stellar,stellar-known-assets,Known Assets Registry,KA,Look up canonical Stellar asset issuer addresses (USDC EURC AQUA yXLM) with provenance and verification commands. Prevents issuer hallucination.,,,1-analysis,,,false,,
 Stellar,stellar-project-brief,Project Brief,PB,Define the dApp concept goals and target users in a concise brief.,,,2-planning,,,false,{planning_artifacts},project-brief
 Stellar,stellar-prd,Stellar dApp PRD,PR,Create or update Product Requirements Document for a Stellar application.,,,2-planning,stellar-project-brief,,true,{planning_artifacts},prd
 Stellar,stellar-epics-stories,Epics and Stories,ES,Break PRD into development epics and user stories with Stellar-specific acceptance criteria.,,,2-planning,stellar-prd,,true,{planning_artifacts},epics-stories
 Stellar,stellar-architecture-doc,Architecture Document,AD,Create technical architecture document covering on-chain vs off-chain Soroban contract design and Horizon integration.,,,3-architecture,stellar-prd,,true,{planning_artifacts},architecture
 Stellar,stellar-setup-environment,Setup Environment,SE,Set up local Stellar development environment with Docker quickstart Stellar CLI and SDK.,,,4-implementation,,,true,{project_knowledge},environment-guide
+Stellar,stellar-doctor,Stellar Doctor,SD,Diagnose toolchain network reachability wallet state contract state and project context. Run before any deployment.,,,4-implementation,,,false,,
 Stellar,stellar-init-contract,Init Contract,IC,Initialize a new Soroban smart contract project with Rust workspace and scaffold.,,,4-implementation,stellar-setup-environment,,false,{implementation_artifacts},contract scaffold
 Stellar,stellar-write-contract,Write Contract,WC,Implement Soroban contract logic including storage types host functions and error handling.,,,4-implementation,stellar-init-contract,,false,{implementation_artifacts},contract code
 Stellar,stellar-test-contract,Test Contract,TC,Write and run comprehensive Soroban contract tests using the Rust test harness.,,,4-implementation,stellar-write-contract,,true,{implementation_artifacts},test suite
@@ -22,3 +24,10 @@ Stellar,stellar-nextjs-wallet,Next.js Wallet,NW,Integrate Freighter wallet into
 Stellar,stellar-nextjs-soroban,Next.js Soroban,NS,Call Soroban contracts from Next.js using Server Components API routes and client-side signing.,,,4-implementation,stellar-nextjs-wallet,,false,{implementation_artifacts},soroban-integration
 Stellar,stellar-freighter-integration,Freighter Integration,FI,Deep Freighter wallet integration — full API reference connection lifecycle and blob signing.,,,4-implementation,stellar-setup-environment,,false,{implementation_artifacts},freighter-integration
 Stellar,stellar-sep10-auth,SEP-10 Auth,S10,Implement SEP-10 Web Authentication with JWT for Next.js API routes and protected endpoints.,,,4-implementation,stellar-nextjs-setup,,false,{implementation_artifacts},sep10-auth
+Stellar,stellar-idea-scoping,Idea Scoping,IS,Pressure-test the hackathon idea against the build window and produce a one-page brief with cut list.,,,5-mentorship,,,false,{planning_artifacts},hackathon-brief
+Stellar,stellar-track-recommendation,Track Recommendation,TR,Match the idea to the right Stellar/Soroban hackathon track and pull the judging rubric.,,,5-mentorship,stellar-idea-scoping,,false,{planning_artifacts},track-decision
+Stellar,stellar-mvp-definition,MVP Definition,MV,Split features into must-have / nice-to-have / skip with hour estimates and a 25% buffer rule.,,,5-mentorship,stellar-idea-scoping,,false,{planning_artifacts},mvp-cut
+Stellar,stellar-judging-criteria,Judging Criteria,JC,Reverse-map the build to the judging rubric and identify gaps before they cost points.,,,5-mentorship,stellar-mvp-definition,,false,{planning_artifacts},rubric-alignment
+Stellar,stellar-demo-prep,Demo Prep,DM,Build the hackathon demo storyboard 2-3 min script and recording checklist with common failure modes.,,,5-mentorship,stellar-mvp-definition,,false,{implementation_artifacts},demo-storyboard
+Stellar,stellar-pitch-coaching,Pitch Coaching,PC,Build the hackathon pitch 3-minute deck outline elevator pitch and judge Q&A drill.,,,5-mentorship,stellar-demo-prep,,false,{planning_artifacts},pitch-script
+Stellar,stellar-submission-prep,Submission Prep,SP,Final pre-submission checklist repo polish README demo video deployed testnet contract IDs and submission form.,,,5-mentorship,stellar-pitch-coaching,,false,{planning_artifacts},submission-confirmation

package/src/stellar-skills/module.yaml

@@ -101,3 +101,10 @@ agents:
     icon: "🎨"
     team: stellar-development
     description: "Builds Next.js App Router dApps connected to the Stellar network. Expert in Freighter wallet integration, Soroban contract calls from React, Horizon data fetching in Server Components, and SEP-10 authentication. Knows exactly when to use Server vs Client Components and never exposes private keys."
+
+  - code: stellar-agent-mentor
+    name: Pera
+    title: Hackathon Mentor
+    icon: "🧭"
+    team: stellar-development
+    description: "Hackathon-arc mentor who guides teams from idea to demo. Scopes ideas to fit hackathon timeboxes, picks the right Stellar/Soroban track, aligns the build to judging criteria, and coaches demo + pitch. Speaks in checklists and time-boxed cuts — every recommendation tied to the submission deadline."

package/tools/installer/commands/init.js

@@ -54,6 +54,7 @@ async function installStellarAgent(targetDir, config) {
     planning_artifacts: `${OUTPUT_DIR}/planning-artifacts`,
     implementation_artifacts: `${OUTPUT_DIR}/implementation-artifacts`,
     project_knowledge: 'docs',
+    skills_version: config.skills_version,
   };
   await fsp.writeFile(
     path.join(stellarDir, 'stellar', 'config.yaml'),
@@ -64,6 +65,7 @@ async function installStellarAgent(targetDir, config) {
   // Write manifest
   const manifest = {
     version: require('../../../package.json').version,
+    skills_version: config.skills_version,
     installed_at: new Date().toISOString(),
     project_name: config.project_name,
   };
@@ -209,6 +211,15 @@ icon = "🎨"
 team = "stellar-development"
 module = "stellar"
 description = "Builds Next.js App Router dApps connected to Stellar — Freighter wallet, Soroban contract calls, SEP-10 auth."
+
+[[agents]]
+code = "stellar-agent-mentor"
+name = "Pera"
+title = "Hackathon Mentor"
+icon = "🧭"
+team = "stellar-development"
+module = "stellar"
+description = "Hackathon mentor — scopes ideas to the timebox, picks the track, aligns to judging criteria, coaches demo and pitch."
 `;
 
   await fsp.writeFile(path.join(stellarDir, 'config.toml'), tomlContent, 'utf8');
@@ -217,8 +228,23 @@ description = "Builds Next.js App Router dApps connected to Stellar — Freighte
 }
 
 async function action(options) {
+  const pkgVersion = require('../../../package.json').version;
+  const requestedVersion = options?.skills || pkgVersion;
+
+  // Pinning warning — we don't ship multi-version download support yet
+  if (requestedVersion !== pkgVersion) {
+    console.error(
+      `⚠️  Skills version mismatch.\n` +
+      `   You requested: ${requestedVersion}\n` +
+      `   This package:  ${pkgVersion}\n\n` +
+      `   To pin to a different version, run:\n` +
+      `     npx stellar-agent@${requestedVersion} init\n\n` +
+      `   Continuing with ${pkgVersion}...\n`
+    );
+  }
+
   await CLIUtils.displayLogo();
-  await prompts.intro('Stellar Agent — AI agent team for Stellar blockchain development');
+  await prompts.intro(`Stellar Agent v${pkgVersion} — AI agent team for Stellar blockchain development`);
 
   // Directory selection
   const rawDir = await prompts.text({
@@ -298,6 +324,7 @@ async function action(options) {
     network_preference: networkPreference,
     primary_language: primaryLanguage,
     communication_language: communicationLanguage,
+    skills_version: pkgVersion,
   };
 
   // Install
@@ -330,6 +357,8 @@ async function action(options) {
 module.exports = {
   command: 'init',
   description: 'Initialize Stellar Agent in your project',
-  options: [],
+  options: [
+    ['--skills <version>', 'Pin to a specific skills version (defaults to the installed package version)'],
+  ],
   action,
 };

package/tools/installer/commands/mcp.js

@@ -0,0 +1,38 @@
+/**
+ * `stellar-agent mcp` — start the MCP server over stdio.
+ *
+ * Invoked by MCP-aware clients (Claude Desktop, Cline, Continue, Zed)
+ * via their server config:
+ *
+ *   {
+ *     "mcpServers": {
+ *       "stellar-agent": {
+ *         "command": "npx",
+ *         "args": ["stellar-agent", "mcp"]
+ *       }
+ *     }
+ *   }
+ */
+
+const path = require('node:path');
+const { spawn } = require('node:child_process');
+
+async function action() {
+  const serverPath = path.join(__dirname, '..', '..', 'mcp-server', 'server.js');
+  const child = spawn(process.execPath, [serverPath], {
+    stdio: 'inherit',
+  });
+
+  child.on('exit', (code) => process.exit(code ?? 0));
+  child.on('error', (err) => {
+    console.error('Failed to start MCP server:', err);
+    process.exit(1);
+  });
+}
+
+module.exports = {
+  command: 'mcp',
+  description: 'Run the Stellar Agent MCP server (stdio). Used by Claude Desktop, Cline, Continue, Zed.',
+  options: [],
+  action,
+};

package/tools/installer/commands/version.js

@@ -0,0 +1,42 @@
+/**
+ * `stellar-agent version` — print CLI version + installed skills version (if any).
+ *
+ * Outputs both:
+ *   - the version of this CLI / npm package
+ *   - the skills version recorded at `_stellar/_config/manifest.yaml`
+ *     if the current directory has stellar-agent installed
+ */
+
+const fs = require('node:fs');
+const path = require('node:path');
+const yaml = require('yaml');
+
+async function action() {
+  const pkg = require('../../../package.json');
+  console.log(`stellar-agent v${pkg.version}`);
+
+  const manifestPath = path.join(process.cwd(), '_stellar', '_config', 'manifest.yaml');
+  if (fs.existsSync(manifestPath)) {
+    try {
+      const manifest = yaml.parse(fs.readFileSync(manifestPath, 'utf8'));
+      console.log(`  installed:     ${manifest.installed_at}`);
+      console.log(`  skills version: ${manifest.skills_version || manifest.version || '(unknown)'}`);
+      console.log(`  project:       ${manifest.project_name || '(unset)'}`);
+      if (manifest.skills_version && manifest.skills_version !== pkg.version) {
+        console.log('');
+        console.log(`  ⚠️  CLI (${pkg.version}) differs from installed skills (${manifest.skills_version}).`);
+        console.log(`     Run \`npx stellar-agent init\` (choose Update) to refresh, or`);
+        console.log(`     run \`npx stellar-agent@${manifest.skills_version} <command>\` to stay pinned.`);
+      }
+    } catch (err) {
+      console.error(`  (could not parse manifest: ${err.message})`);
+    }
+  }
+}
+
+module.exports = {
+  command: 'version',
+  description: 'Print the CLI version and the installed skills version (if any)',
+  options: [],
+  action,
+};

package/tools/installer/stellar-cli.js

@@ -55,7 +55,7 @@ if (process.stdin.isTTY) {
 }
 
 const commandsPath = path.join(__dirname, 'commands');
-const ALLOWED_COMMANDS = ['init'];
+const ALLOWED_COMMANDS = ['init', 'mcp', 'version'];
 
 const commands = {};
 for (const name of ALLOWED_COMMANDS) {

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);
+});