clare: Skill for Codex

CLARE MCP Server

What this skill does: Scaffolds a minimal MCP (Model Context Protocol) server that exposes CLARE's enforcement primitives — verify-ci.sh and autonomy.yml — as typed tool calls. Any MCP-compatible agent or orchestrator can then call CLARE tools without needing bash access or CLARE-specific prompt engineering.

When to use: When running multi-agent pipelines, headless agents, or any workflow where you need CLARE enforcement available as a structured tool rather than a bash script.

Output: A mcp/ directory containing a runnable MCP server + registration instructions.

---

Context

CLARE's two core enforcement primitives are:

1. clare/verify-ci.sh — runs all CI checks, exits non-zero on failure
2. clare/autonomy.yml — YAML file mapping file paths to autonomy levels

This skill exposes them as three MCP tools:

Tool	Input	Output
clare_verify	(none)	{status, passed[], failed[{check, output}], summary}
clare_check_autonomy	{path: string}	{path, matched_rule, level, reason}
clare_list_humans_only	(none)	{humans_only_paths: string[]}

---

Instructions

When this skill is invoked, generate a CLARE MCP server for the current project.

Step 1: Detect the project runtime

Check for package.json → generate Node.js server. Check for pyproject.toml or requirements.txt → generate Python server. If both exist, ask the user which runtime to use. If neither, default to Node.js.

Step 2: Scaffold the server

For Node.js — create mcp/clare-server.js:

#!/usr/bin/env node
// @generated — regenerate from clare/templates/skills/mcp-server.md, do not hand-edit
//
// CLARE MCP Server
// Exposes CLARE enforcement primitives as MCP tool calls.
// See docs/agentic.md for usage in multi-agent pipelines.

import { Server } from '@modelcontextprotocol/sdk/server/index.js';
import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
import { CallToolRequestSchema, ListToolsRequestSchema } from '@modelcontextprotocol/sdk/types.js';
import { execSync } from 'child_process';
import { readFileSync } from 'fs';
import { resolve, dirname } from 'path';
import { fileURLToPath } from 'url';
import yaml from 'js-yaml';

const __dirname = dirname(fileURLToPath(import.meta.url));
const PROJECT_ROOT = resolve(__dirname, '..');

const server = new Server(
  { name: 'clare', version: '1.0.0' },
  { capabilities: { tools: {} } }
);

server.setRequestHandler(ListToolsRequestSchema, async () => ({
  tools: [
    {
      name: 'clare_verify',
      description: 'Run clare/verify-ci.sh and return structured pass/fail results. Call this after any code generation before reporting work complete.',
      inputSchema: { type: 'object', properties: {}, required: [] }
    },
    {
      name: 'clare_check_autonomy',
      description: 'Look up the autonomy level for a file path in clare/autonomy.yml. Call this before modifying any file.',
      inputSchema: {
        type: 'object',
        properties: {
          path: { type: 'string', description: 'File path relative to project root' }
        },
        required: ['path']
      }
    },
    {
      name: 'clare_list_humans_only',
      description: 'List all humans-only paths from clare/autonomy.yml. Call this as a pre-flight check before delegating tasks to sub-agents.',
      inputSchema: { type: 'object', properties: {}, required: [] }
    }
  ]
}));

server.setRequestHandler(CallToolRequestSchema, async (request) => {
  const { name, arguments: args } = request.params;

  if (name === 'clare_verify') {
    try {
      const output = execSync(`${PROJECT_ROOT}/clare/verify-ci.sh`, {
        cwd: PROJECT_ROOT,
        encoding: 'utf8',
        stdio: ['pipe', 'pipe', 'pipe']
      });
      return {
        content: [{ type: 'text', text: JSON.stringify({ status: 'passed', output, summary: 'All checks passed' }) }]
      };
    } catch (err) {
      const output = err.stdout + err.stderr;
      const failedChecks = (output.match(/❌ (.+)/g) || []).map(l => l.replace('❌ ', '').trim());
      return {
        content: [{ type: 'text', text: JSON.stringify({ status: 'failed', failed: failedChecks, output, summary: `${failedChecks.length} check(s) failed` }) }]
      };
    }
  }

  if (name === 'clare_check_autonomy') {
    const targetPath = args.path;
    const autonomyFile = readFileSync(`${PROJECT_ROOT}/clare/autonomy.yml`, 'utf8');
    const autonomy = yaml.load(autonomyFile);
    
    const modules = autonomy.modules || [];
    let matched = modules.find(m => m.path !== '*' && targetPath.startsWith(m.path));
    if (!matched) matched = modules.find(m => m.path === '*');
    
    return {
      content: [{
        type: 'text',
        text: JSON.stringify({
          path: targetPath,
          matched_rule: matched?.path || 'none',
          level: matched?.level || 'unknown',
          reason: matched?.reason || ''
        })
      }]
    };
  }

  if (name === 'clare_list_humans_only') {
    const autonomyFile = readFileSync(`${PROJECT_ROOT}/clare/autonomy.yml`, 'utf8');
    const autonomy = yaml.load(autonomyFile);
    const humansOnly = (autonomy.modules || [])
      .filter(m => m.level === 'humans-only')
      .map(m => m.path);
    return {
      content: [{ type: 'text', text: JSON.stringify({ humans_only_paths: humansOnly }) }]
    };
  }

  throw new Error(`Unknown tool: ${name}`);
});

const transport = new StdioServerTransport();
await server.connect(transport);