mcp-server.js

#!/usr/bin/env node
'use strict';

/**
 * Knowledge-as-Code — MCP Server
 * Zero-dependency Model Context Protocol server over JSON-RPC / stdio.
 *
 * Reads project.yml at startup and exposes entity data as MCP tools
 * with dynamic names derived from the configured ontology.
 *
 * Usage: node mcp-server.js   (called by MCP host via stdio)
 */

const fs = require('fs');
const path = require('path');
const packageMetadata = require('./package.json');
const { loadProjectData } = require('./scripts/lib/data-loaders');
const { validateProjectData } = require('./scripts/lib/validation');
const { parseYaml } = require('./scripts/lib/parsers');

const ROOT = __dirname;

// ---------------------------------------------------------------------------
// Shared helpers (from scripts/build.js)
// ---------------------------------------------------------------------------

function slugify(str) {
    return String(str || '').toLowerCase().replace(/[^a-z0-9]+/g, '-').replace(/^-|-$/g, '');
}

function escapeHTML(str) {
    return String(str || '').replace(/&/g, '&amp;').replace(/</g, '&lt;').replace(/>/g, '&gt;').replace(/"/g, '&quot;');
}

function humanizeId(id) {
    return String(id || '').replace(/-/g, ' ').replace(/\b\w/g, c => c.toUpperCase());
}

// ---------------------------------------------------------------------------
// Load project data
// ---------------------------------------------------------------------------

const config = (() => {
    const configPath = path.join(ROOT, 'project.yml');
    if (!fs.existsSync(configPath)) {
        process.stderr.write('Error: project.yml not found.\n');
        process.exit(1);
    }
    return parseYaml(fs.readFileSync(configPath, 'utf-8'));
})();

let loaded;
try {
    loaded = loadProjectData(ROOT, config, { requireMapping: true });
    validateProjectData(config, loaded, ROOT);
} catch (error) {
    process.stderr.write(`Error: ${error.message}\n`);
    process.exit(1);
}
const { primaries, containers, authorities, mappings } = loaded;

// ---------------------------------------------------------------------------
// Tool name derivation
// ---------------------------------------------------------------------------

const primaryName = slugify(config.entities?.primary?.name || 'primary');
const primaryPlural = slugify(config.entities?.primary?.plural || 'primaries');
const containerName = slugify(config.entities?.container?.name || 'container');
const containerPlural = slugify(config.entities?.container?.plural || 'containers');
const authorityName = slugify(config.entities?.authority?.name || 'authority');
const authorityPlural = slugify(config.entities?.authority?.plural || 'authorities');

// ---------------------------------------------------------------------------
// Boundary helper
// ---------------------------------------------------------------------------

function boundary(message, suggestions, why) {
    const b = { message, suggestions: suggestions || [] };
    if (why) b.why = why;
    return b;
}

// ---------------------------------------------------------------------------
// Tool definitions
// ---------------------------------------------------------------------------

function getToolDefinitions() {
    const pName = config.entities?.primary?.name || 'Primary';
    const pPlural = config.entities?.primary?.plural || 'Primaries';
    const cName = config.entities?.container?.name || 'Container';
    const cPlural = config.entities?.container?.plural || 'Containers';
    const aName = config.entities?.authority?.name || 'Authority';
    const aPlural = config.entities?.authority?.plural || 'Authorities';

    return [
        {
            name: `list_${primaryPlural}`,
            description: `List all ${pPlural.toLowerCase()} in the knowledge base. Returns id, title, and group for each.`,
            inputSchema: { type: 'object', properties: {}, required: [] }
        },
        {
            name: `get_${primaryName}`,
            description: `Get a single ${pName.toLowerCase()} by its ID. Returns all frontmatter fields and body content.`,
            inputSchema: {
                type: 'object',
                properties: { id: { type: 'string', description: `The ${pName.toLowerCase()} ID (filename without .md)` } },
                required: ['id']
            }
        },
        {
            name: `list_${containerPlural}`,
            description: `List all ${cPlural.toLowerCase()} in the knowledge base. Returns id, title, status, and authority.`,
            inputSchema: { type: 'object', properties: {}, required: [] }
        },
        {
            name: `get_${containerName}`,
            description: `Get a single ${cName.toLowerCase()} by its ID. Returns frontmatter, timeline, and provisions.`,
            inputSchema: {
                type: 'object',
                properties: { id: { type: 'string', description: `The ${cName.toLowerCase()} ID (filename without .md)` } },
                required: ['id']
            }
        },
        {
            name: `list_${authorityPlural}`,
            description: `List all ${aPlural.toLowerCase()} in the knowledge base.`,
            inputSchema: { type: 'object', properties: {}, required: [] }
        },
        {
            name: `get_${authorityName}`,
            description: `Get a single ${aName.toLowerCase()} by its ID. Returns all frontmatter fields and body content.`,
            inputSchema: {
                type: 'object',
                properties: { id: { type: 'string', description: `The ${aName.toLowerCase()} ID (filename without .md)` } },
                required: ['id']
            }
        },
        {
            name: 'search',
            description: 'Full-text search across all entities in the knowledge base. Searches titles, IDs, and body content.',
            inputSchema: {
                type: 'object',
                properties: { query: { type: 'string', description: 'Search query (case-insensitive substring match)' } },
                required: ['query']
            }
        },
        {
            name: 'get_matrix',
            description: `Coverage matrix showing which ${pPlural.toLowerCase()} are addressed by which ${cPlural.toLowerCase()}.`,
            inputSchema: { type: 'object', properties: {}, required: [] }
        },
        {
            name: 'get_mappings',
            description: `All mapping entries connecting ${cPlural.toLowerCase()} to ${pPlural.toLowerCase()} via ${config.entities?.secondary?.plural?.toLowerCase() || 'secondaries'}.`,
            inputSchema: { type: 'object', properties: {}, required: [] }
        }
    ];
}

// ---------------------------------------------------------------------------
// Tool dispatch
// ---------------------------------------------------------------------------

function handleToolCall(name, args) {
    // --- list primaries ---
    if (name === `list_${primaryPlural}`) {
        const items = primaries.map(p => ({ id: p.id, title: p.name || p.title || humanizeId(p.id), group: p.group || '' }));
        return { content: [{ type: 'text', text: JSON.stringify(items, null, 2) }] };
    }

    // --- get primary ---
    if (name === `get_${primaryName}`) {
        const entity = primaries.find(p => p.id === args.id);
        if (!entity) {
            return {
                content: [{ type: 'text', text: JSON.stringify({
                    error: `${config.entities?.primary?.name || 'Primary'} not found: ${args.id}`,
                    boundary: boundary(
                        `No ${(config.entities?.primary?.name || 'primary').toLowerCase()} with id "${args.id}" exists.`,
                        [`Use list_${primaryPlural} to see available IDs`, 'Check spelling and use lowercase-hyphenated format'],
                        'IDs are derived from filenames in the data directory'
                    )
                }, null, 2) }],
                isError: true
            };
        }
        const { _body, _file, content, file, ...rest } = entity;
        return { content: [{ type: 'text', text: JSON.stringify({ ...rest, body: _body }, null, 2) }] };
    }

    // --- list containers ---
    if (name === `list_${containerPlural}`) {
        const items = containers.map(c => ({ id: c.id, title: c.name || c.title || humanizeId(c.id), status: c.status || '', authority: c.authority || '' }));
        return { content: [{ type: 'text', text: JSON.stringify(items, null, 2) }] };
    }

    // --- get container ---
    if (name === `get_${containerName}`) {
        const entity = containers.find(c => c.id === args.id);
        if (!entity) {
            return {
                content: [{ type: 'text', text: JSON.stringify({
                    error: `${config.entities?.container?.name || 'Container'} not found: ${args.id}`,
                    boundary: boundary(
                        `No ${(config.entities?.container?.name || 'container').toLowerCase()} with id "${args.id}" exists.`,
                        [`Use list_${containerPlural} to see available IDs`, 'Check spelling and use lowercase-hyphenated format'],
                        'IDs are derived from filenames in the data directory'
                    )
                }, null, 2) }],
                isError: true
            };
        }
        const { _body, _file, content, file, ...rest } = entity;
        return { content: [{ type: 'text', text: JSON.stringify({ ...rest, body: _body }, null, 2) }] };
    }

    // --- list authorities ---
    if (name === `list_${authorityPlural}`) {
        const items = authorities.map(a => ({ id: a.id, title: a.name || a.title || humanizeId(a.id), type: a.type || '' }));
        return { content: [{ type: 'text', text: JSON.stringify(items, null, 2) }] };
    }

    // --- get authority ---
    if (name === `get_${authorityName}`) {
        const entity = authorities.find(a => a.id === args.id);
        if (!entity) {
            return {
                content: [{ type: 'text', text: JSON.stringify({
                    error: `${config.entities?.authority?.name || 'Authority'} not found: ${args.id}`,
                    boundary: boundary(
                        `No ${(config.entities?.authority?.name || 'authority').toLowerCase()} with id "${args.id}" exists.`,
                        [`Use list_${authorityPlural} to see available IDs`, 'Check spelling and use lowercase-hyphenated format'],
                        'IDs are derived from filenames in the data directory'
                    )
                }, null, 2) }],
                isError: true
            };
        }
        const { _body, _file, content, file, ...rest } = entity;
        return { content: [{ type: 'text', text: JSON.stringify({ ...rest, body: _body }, null, 2) }] };
    }

    // --- search ---
    if (name === 'search') {
        const q = (args.query || '').toLowerCase();
        if (!q) {
            return {
                content: [{ type: 'text', text: JSON.stringify({
                    error: 'Empty search query',
                    boundary: boundary('A non-empty query string is required.', ['Provide a keyword or phrase to search for'])
                }, null, 2) }],
                isError: true
            };
        }

        const results = [];
        const searchEntity = (entity, type) => {
            const haystack = [entity.id, entity.name || entity.title || '', entity._body || ''].join(' ').toLowerCase();
            if (haystack.includes(q)) {
                results.push({ type, id: entity.id, title: entity.name || entity.title || humanizeId(entity.id) });
            }
        };

        primaries.forEach(e => searchEntity(e, config.entities?.primary?.name || 'primary'));
        containers.forEach(e => searchEntity(e, config.entities?.container?.name || 'container'));
        authorities.forEach(e => searchEntity(e, config.entities?.authority?.name || 'authority'));

        return { content: [{ type: 'text', text: JSON.stringify({ query: args.query, count: results.length, results }, null, 2) }] };
    }

    // --- get_matrix ---
    if (name === 'get_matrix') {
        const matrix = {};
        for (const c of containers) {
            matrix[c.id] = {};
            for (const p of primaries) matrix[c.id][p.id] = false;
        }
        for (const m of mappings) {
            const cId = m.regulation || m.container || m.framework;
            if (cId && matrix[cId]) {
                for (const obl of (m.obligations || [])) {
                    if (matrix[cId][obl] !== undefined) matrix[cId][obl] = true;
                }
            }
        }
        return { content: [{ type: 'text', text: JSON.stringify(matrix, null, 2) }] };
    }

    // --- get_mappings ---
    if (name === 'get_mappings') {
        return { content: [{ type: 'text', text: JSON.stringify(mappings, null, 2) }] };
    }

    // --- unknown tool ---
    return {
        content: [{ type: 'text', text: JSON.stringify({
            error: `Unknown tool: ${name}`,
            boundary: boundary(
                `The tool "${name}" does not exist on this server.`,
                ['Use tools/list to see available tools'],
                'Tool names are derived from entity names in project.yml'
            )
        }, null, 2) }],
        isError: true
    };
}

// ---------------------------------------------------------------------------
// JSON-RPC / MCP protocol
// ---------------------------------------------------------------------------

// Dual-era server (MCP spec revision 2026-07-28): a legacy client selects the
// 2024-11-05 semantics via `initialize`; a modern client carries per-request
// `_meta` and is served statelessly. Both eras run concurrently in-process.
const SUPPORTED_PROTOCOL_VERSIONS = ['2026-07-28', '2024-11-05'];
// Static data regenerated on a known cadence — safe to cache for an hour.
const CACHE_TTL_MS = 3600000;
const CACHE_SCOPE = 'public';

function makeResponse(id, result) {
    return JSON.stringify({ jsonrpc: '2.0', id, result });
}

function makeError(id, code, message, data) {
    const error = { code, message };
    if (data !== undefined) error.data = data;
    return JSON.stringify({ jsonrpc: '2.0', id, error });
}

function handleMessage(msg) {
    const { id, method, params } = msg;
    const hasId = Object.prototype.hasOwnProperty.call(msg, 'id');

    // Modern requests declare their protocol version per request. Unknown
    // versions are rejected; requests without `_meta` (legacy handshake or
    // bare requests) are served exactly as before.
    const requestedVersion = params?._meta?.['io.modelcontextprotocol/protocolVersion'];
    if (requestedVersion !== undefined && !SUPPORTED_PROTOCOL_VERSIONS.includes(requestedVersion)) {
        if (!hasId) return null;
        return makeError(id, -32022, 'Unsupported protocol version', {
            supported: SUPPORTED_PROTOCOL_VERSIONS,
            requested: requestedVersion
        });
    }

    if (method === 'initialize') {
        if (!hasId) return null;
        const clientVersion = params?.protocolVersion;
        return makeResponse(id, {
            resultType: 'complete',
            protocolVersion: SUPPORTED_PROTOCOL_VERSIONS.includes(clientVersion) ? clientVersion : '2024-11-05',
            capabilities: { tools: {} },
            serverInfo: {
                name: config.name || 'Knowledge Base MCP',
                version: packageMetadata.version
            }
        });
    }

    if (method === 'notifications/initialized') {
        return null; // notification, no response
    }

    if (method === 'server/discover') {
        if (!hasId) return null;
        const result = {
            resultType: 'complete',
            supportedVersions: SUPPORTED_PROTOCOL_VERSIONS,
            capabilities: { tools: {} },
            _meta: {
                'io.modelcontextprotocol/serverInfo': {
                    name: config.name || 'Knowledge Base MCP',
                    version: packageMetadata.version
                }
            },
            ttlMs: CACHE_TTL_MS,
            cacheScope: CACHE_SCOPE
        };
        if (config.description) result.instructions = config.description;
        return makeResponse(id, result);
    }

    if (method === 'tools/list') {
        if (!hasId) return null;
        return makeResponse(id, {
            resultType: 'complete',
            tools: getToolDefinitions(),
            ttlMs: CACHE_TTL_MS,
            cacheScope: CACHE_SCOPE
        });
    }

    if (method === 'tools/call') {
        if (!hasId) return null;
        const toolName = params?.name;
        const toolArgs = params?.arguments || {};
        const result = handleToolCall(toolName, toolArgs);
        return makeResponse(id, { resultType: 'complete', ...result });
    }

    if (!hasId) return null;
    return makeError(id, -32601, `Method not found: ${method}`);
}

// ---------------------------------------------------------------------------
// Stdio transport
// ---------------------------------------------------------------------------

let buffer = '';

process.stdin.setEncoding('utf-8');
process.stdin.on('data', chunk => {
    buffer += chunk;
    let newlineIdx;
    while ((newlineIdx = buffer.indexOf('\n')) !== -1) {
        const line = buffer.slice(0, newlineIdx).trim();
        buffer = buffer.slice(newlineIdx + 1);
        if (!line) continue;

        try {
            const msg = JSON.parse(line);
            const response = handleMessage(msg);
            if (response) {
                process.stdout.write(response + '\n');
            }
        } catch (err) {
            const errResp = makeError(null, -32700, 'Parse error: ' + err.message);
            process.stdout.write(errResp + '\n');
        }
    }
});

process.stdin.on('end', () => process.exit(0));