@precepts/mcp-server 1.0.0

package/LICENSE

@@ -0,0 +1,31 @@
+# Licensing
+
+This repository uses a split-license model. Different parts of the
+repository are covered by different licenses:
+
+## Documentation Content - CC BY-SA 4.0
+
+Standards content is maintained in a separate repository
+(precepts-dev/standards) and licensed under the Creative Commons
+Attribution-ShareAlike 4.0 International License.
+
+See LICENSE-CONTENT for details.
+
+## Source Code - AGPL 3.0
+
+All source code files including `packages/`, `.github/workflows/`,
+configuration files (*.ts, *.js, *.json), and any other programming
+any other programming language files are licensed under the GNU Affero
+General Public License v3.0.
+
+See LICENSE-CODE for details.
+
+## Why Two Licenses?
+
+- The **content** license (CC BY-SA 4.0) ensures standards are freely
+  usable by everyone - individuals, companies, and AI tools - while
+  requiring attribution and that derivatives remain open.
+
+- The **code** license (AGPL 3.0) ensures the tooling remains open
+  source while protecting against proprietary forks being deployed
+  as competing services without sharing modifications.

package/dist/index.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/index.js

@@ -0,0 +1,164 @@
+#!/usr/bin/env node
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { createRequire } from "node:module";
+import path from "node:path";
+import { z } from "zod";
+import { loadStandards, searchStandards } from "./standards.js";
+const require_ = createRequire(import.meta.url);
+// Resolve docs root: prefer env var, then locate @precepts/standards via its exported schema file
+const DOCS_ROOT = process.env.PRECEPTS_DOCS_ROOT ??
+    path.join(path.dirname(require_.resolve("@precepts/standards/schema/standards.schema.json")), "..", "standards");
+const server = new McpServer({
+    name: "precepts-standards",
+    version: "0.1.0",
+});
+// Load standards at startup
+const standards = loadStandards(DOCS_ROOT);
+// ── Tool: list_standards ──────────────────────────────────────────
+server.tool("list_standards", "List all available standards. Optionally filter by domain, status, or category.", {
+    domain: z
+        .string()
+        .optional()
+        .describe("Filter by domain (e.g., integration, product, ux, project)"),
+    status: z
+        .string()
+        .optional()
+        .describe("Filter by status (DRAFT, MANDATORY, RECOMMENDED, DEPRECATED)"),
+    category: z
+        .string()
+        .optional()
+        .describe("Filter by category (e.g., format, protocol, security)"),
+    documentType: z
+        .string()
+        .optional()
+        .describe("Filter by document type (standard, guideline, governance, best-practice)"),
+}, async ({ domain, status, category, documentType }) => {
+    let filtered = standards;
+    if (domain)
+        filtered = filtered.filter((s) => s.domain === domain);
+    if (status)
+        filtered = filtered.filter((s) => s.metadata.status === status);
+    if (category)
+        filtered = filtered.filter((s) => s.metadata.category === category);
+    if (documentType)
+        filtered = filtered.filter((s) => s.metadata.documentType === documentType);
+    const listing = filtered.map((s) => ({
+        identifier: s.metadata.identifier,
+        name: s.metadata.name,
+        version: s.metadata.version,
+        status: s.metadata.status,
+        domain: s.domain,
+        documentType: s.metadata.documentType ?? "N/A",
+        category: s.metadata.category ?? "N/A",
+        summary: s.metadata.machine_summary ?? "",
+    }));
+    return {
+        content: [
+            {
+                type: "text",
+                text: JSON.stringify(listing, null, 2),
+            },
+        ],
+    };
+});
+// ── Tool: get_standard ────────────────────────────────────────────
+server.tool("get_standard", "Retrieve the full content of a specific standard by its identifier (e.g., INTG-STD-001).", {
+    identifier: z.string().describe("The standard identifier (e.g., INTG-STD-001)"),
+}, async ({ identifier }) => {
+    const std = standards.find((s) => s.metadata.identifier.toLowerCase() === identifier.toLowerCase());
+    if (!std) {
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: `Standard "${identifier}" not found. Use list_standards to see available standards.`,
+                },
+            ],
+            isError: true,
+        };
+    }
+    const header = Object.entries(std.metadata)
+        .map(([k, v]) => `${k}: ${JSON.stringify(v)}`)
+        .join("\n");
+    return {
+        content: [
+            {
+                type: "text",
+                text: `--- Metadata ---\n${header}\n\n--- Content ---\n${std.content}`,
+            },
+        ],
+    };
+});
+// ── Tool: search_standards ────────────────────────────────────────
+server.tool("search_standards", "Full-text search across all standards. Returns matching standards with their metadata.", {
+    query: z.string().describe("Search query (searches identifier, name, summary, and body)"),
+    domain: z.string().optional().describe("Limit search to a specific domain"),
+    status: z.string().optional().describe("Limit search to a specific status"),
+}, async ({ query, domain, status }) => {
+    const results = searchStandards(standards, query, { domain, status });
+    const listing = results.map((s) => ({
+        identifier: s.metadata.identifier,
+        name: s.metadata.name,
+        domain: s.domain,
+        status: s.metadata.status,
+        summary: s.metadata.machine_summary ?? "",
+        excerpt: s.content.slice(0, 300) + (s.content.length > 300 ? "..." : ""),
+    }));
+    return {
+        content: [
+            {
+                type: "text",
+                text: results.length === 0
+                    ? `No standards found matching "${query}".`
+                    : JSON.stringify(listing, null, 2),
+            },
+        ],
+    };
+});
+// ── Resources: each standard as a resource ────────────────────────
+for (const std of standards) {
+    server.resource(std.metadata.identifier, `standards://${std.metadata.identifier}`, {
+        description: std.metadata.name,
+        mimeType: "text/markdown",
+    }, async () => ({
+        contents: [
+            {
+                uri: `standards://${std.metadata.identifier}`,
+                mimeType: "text/markdown",
+                text: std.content,
+            },
+        ],
+    }));
+}
+// ── Resource: standards index ─────────────────────────────────────
+server.resource("standards-index", "standards://index", {
+    description: "Index of all available standards with metadata",
+    mimeType: "application/json",
+}, async () => ({
+    contents: [
+        {
+            uri: "standards://index",
+            mimeType: "application/json",
+            text: JSON.stringify(standards.map((s) => ({
+                identifier: s.metadata.identifier,
+                name: s.metadata.name,
+                version: s.metadata.version,
+                status: s.metadata.status,
+                domain: s.domain,
+                documentType: s.metadata.documentType,
+                category: s.metadata.category,
+            })), null, 2),
+        },
+    ],
+}));
+// ── Start server ──────────────────────────────────────────────────
+async function main() {
+    const transport = new StdioServerTransport();
+    await server.connect(transport);
+    console.error(`Precepts MCP server running. Loaded ${standards.length} standard(s) from ${DOCS_ROOT}`);
+}
+main().catch((err) => {
+    console.error("Failed to start MCP server:", err);
+    process.exit(1);
+});

package/dist/standards.d.ts

@@ -0,0 +1,32 @@
+export interface StandardMetadata {
+    identifier: string;
+    name: string;
+    version: string;
+    status: "DRAFT" | "MANDATORY" | "RECOMMENDED" | "DEPRECATED";
+    domain?: string;
+    documentType?: "standard" | "guideline" | "governance" | "best-practice";
+    category?: string;
+    appliesTo?: string[];
+    dependsOn?: string[];
+    supersedes?: string;
+    machine_summary?: string;
+    [key: string]: unknown;
+}
+export interface Standard {
+    metadata: StandardMetadata;
+    content: string;
+    filePath: string;
+    domain: string;
+}
+/**
+ * Load and parse all standards documents from the docs directory.
+ */
+export declare function loadStandards(docsRoot: string): Standard[];
+/**
+ * Simple full-text search across standards.
+ */
+export declare function searchStandards(standards: Standard[], query: string, filters?: {
+    domain?: string;
+    status?: string;
+    category?: string;
+}): Standard[];

package/dist/standards.js

@@ -0,0 +1,82 @@
+import fs from "node:fs";
+import path from "node:path";
+import matter from "gray-matter";
+/**
+ * Recursively find all .md files under a directory.
+ */
+function findMarkdownFiles(dir) {
+    const results = [];
+    if (!fs.existsSync(dir))
+        return results;
+    const entries = fs.readdirSync(dir, { withFileTypes: true });
+    for (const entry of entries) {
+        const fullPath = path.join(dir, entry.name);
+        if (entry.isDirectory()) {
+            results.push(...findMarkdownFiles(fullPath));
+        }
+        else if (entry.name.endsWith(".md") && !entry.name.startsWith("_")) {
+            results.push(fullPath);
+        }
+    }
+    return results;
+}
+/**
+ * Infer the domain from the file path.
+ * e.g., docs/integration/standards/INTG-STD-001.md → "integration"
+ */
+function inferDomain(filePath, docsRoot) {
+    const relative = path.relative(docsRoot, filePath);
+    const parts = relative.split(path.sep);
+    return parts[0] ?? "unknown";
+}
+/**
+ * Load and parse all standards documents from the docs directory.
+ */
+export function loadStandards(docsRoot) {
+    const standards = [];
+    const files = findMarkdownFiles(docsRoot);
+    for (const filePath of files) {
+        try {
+            const raw = fs.readFileSync(filePath, "utf-8");
+            const { data, content } = matter(raw);
+            // Only include files with an identifier (i.e., actual standards/guidelines)
+            if (!data.identifier)
+                continue;
+            standards.push({
+                metadata: data,
+                content,
+                filePath,
+                domain: inferDomain(filePath, docsRoot),
+            });
+        }
+        catch (err) {
+            console.error(`Skipping unparsable file: ${filePath}`, err);
+        }
+    }
+    return standards;
+}
+/**
+ * Simple full-text search across standards.
+ */
+export function searchStandards(standards, query, filters) {
+    const queryLower = query.toLowerCase();
+    return standards.filter((std) => {
+        // Apply filters first
+        if (filters?.domain && std.domain !== filters.domain)
+            return false;
+        if (filters?.status && std.metadata.status !== filters.status)
+            return false;
+        if (filters?.category && std.metadata.category !== filters.category)
+            return false;
+        // Full-text search across identifier, name, content, and machine_summary
+        const searchable = [
+            std.metadata.identifier,
+            std.metadata.name,
+            std.metadata.machine_summary ?? "",
+            std.content,
+        ]
+            .join(" ")
+            .toLowerCase();
+        return searchable.includes(queryLower);
+    });
+}

package/package.json

@@ -0,0 +1,36 @@
+{
+  "name": "@precepts/mcp-server",
+  "version": "1.0.0",
+  "description": "MCP server exposing Precepts standards as tools and resources for AI agents",
+  "type": "module",
+  "license": "AGPL-3.0-only",
+  "publishConfig": {
+    "access": "public"
+  },
+  "files": [
+    "dist"
+  ],
+  "main": "dist/index.js",
+  "bin": {
+    "precepts-mcp": "dist/index.js"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.29.0",
+    "@precepts/standards": "^0.3.1",
+    "gray-matter": "^4.0.3",
+    "zod": "^4.4.3"
+  },
+  "devDependencies": {
+    "@types/node": "^22.0.0",
+    "tsx": "^4.19.0",
+    "typescript": "~5.6.2"
+  },
+  "engines": {
+    "node": ">=20.0"
+  },
+  "scripts": {
+    "build": "tsc",
+    "start": "node dist/index.js",
+    "dev": "tsx src/index.ts"
+  }
+}