@yourtechtribe-labs/koncept-mcp-server 0.1.0-alpha.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Albert Gil López — yourtechtribe-labs
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,52 @@
+# @yourtechtribe-labs/koncept-mcp-server
+
+> MCP stdio server exposing [koncepto](https://github.com/yourtechtribe-labs/koncept-mcp) — semantic concept graph tools for AI coding agents.
+
+**Status**: pre-alpha (`v0.1.0-alpha.1`).
+
+## What it does
+
+Reads a project's `.koncept/concepts/*.yaml` registry and exposes 4 read-only tools over the [Model Context Protocol](https://modelcontextprotocol.io):
+
+| Tool | Purpose |
+|---|---|
+| `koncept-search` | Full-text + tag search across concepts |
+| `koncept-get` | Fetch a concept by id (full payload) |
+| `koncept-for-file` | List concepts where a file appears as participant |
+| `koncept-invariants-at-scope` | Return invariants whose concept overlaps a scope |
+
+Drop this in front of Claude Code, Cursor, or any other MCP client and the agent gains read-Step-0 awareness of cross-cutting semantic facts that don't show up in the AST.
+
+## Install (Claude Code)
+
+```bash
+claude mcp add --scope user koncepto -- \
+  npx -y @yourtechtribe-labs/koncept-mcp-server@alpha "$PWD"
+```
+
+## Install (other MCP clients)
+
+The server expects a single positional arg: the project root containing a `.koncept/` directory.
+
+```bash
+npx -y @yourtechtribe-labs/koncept-mcp-server@alpha /path/to/project
+```
+
+## Bootstrap your project
+
+Use the CLI ([`@yourtechtribe-labs/koncept-cli`](https://www.npmjs.com/package/@yourtechtribe-labs/koncept-cli)) to initialize the registry:
+
+```bash
+pnpm add -D @yourtechtribe-labs/koncept-cli@alpha
+npx koncepto init
+```
+
+Then write concepts under `.koncept/concepts/<id>.yaml` and `npx koncepto verify`.
+
+## License
+
+MIT — see [LICENSE](./LICENSE).
+
+## Repository
+
+Source, issues, schema docs, and roadmap at [github.com/yourtechtribe-labs/koncept-mcp](https://github.com/yourtechtribe-labs/koncept-mcp).

package/dist/index.d.ts

@@ -0,0 +1,3 @@
+#!/usr/bin/env node
+export {};
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":""}

package/dist/index.js

@@ -0,0 +1,18 @@
+#!/usr/bin/env node
+import { resolve } from 'node:path';
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import { createServer } from './server.js';
+import { registerAllTools } from './tools/index.js';
+async function main() {
+    const rawRoot = process.argv[2] ?? process.cwd();
+    const rootDir = resolve(rawRoot);
+    const { mcp } = createServer({ rootDir });
+    registerAllTools(mcp, { rootDir });
+    const transport = new StdioServerTransport();
+    await mcp.connect(transport);
+}
+main().catch((err) => {
+    process.stderr.write(`koncept-mcp-server fatal: ${String(err)}\n`);
+    process.exit(1);
+});
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";AACA,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAA;AACnC,OAAO,EAAE,oBAAoB,EAAE,MAAM,2CAA2C,CAAA;AAChF,OAAO,EAAE,YAAY,EAAE,MAAM,aAAa,CAAA;AAC1C,OAAO,EAAE,gBAAgB,EAAE,MAAM,kBAAkB,CAAA;AAEnD,KAAK,UAAU,IAAI;IACjB,MAAM,OAAO,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,IAAI,OAAO,CAAC,GAAG,EAAE,CAAA;IAChD,MAAM,OAAO,GAAG,OAAO,CAAC,OAAO,CAAC,CAAA;IAEhC,MAAM,EAAE,GAAG,EAAE,GAAG,YAAY,CAAC,EAAE,OAAO,EAAE,CAAC,CAAA;IACzC,gBAAgB,CAAC,GAAG,EAAE,EAAE,OAAO,EAAE,CAAC,CAAA;IAElC,MAAM,SAAS,GAAG,IAAI,oBAAoB,EAAE,CAAA;IAC5C,MAAM,GAAG,CAAC,OAAO,CAAC,SAAS,CAAC,CAAA;AAC9B,CAAC;AAED,IAAI,EAAE,CAAC,KAAK,CAAC,CAAC,GAAY,EAAE,EAAE;IAC5B,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,6BAA6B,MAAM,CAAC,GAAG,CAAC,IAAI,CAAC,CAAA;IAClE,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAA;AACjB,CAAC,CAAC,CAAA"}

package/dist/server.d.ts

@@ -0,0 +1,9 @@
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+export interface ServerOptions {
+    rootDir: string;
+}
+export declare function createServer(opts: ServerOptions): {
+    mcp: McpServer;
+    rootDir: string;
+};
+//# sourceMappingURL=server.d.ts.map

package/dist/server.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"server.d.ts","sourceRoot":"","sources":["../src/server.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,MAAM,yCAAyC,CAAA;AAGnE,MAAM,WAAW,aAAa;IAC5B,OAAO,EAAE,MAAM,CAAA;CAChB;AAED,wBAAgB,YAAY,CAAC,IAAI,EAAE,aAAa,GAAG;IACjD,GAAG,EAAE,SAAS,CAAA;IACd,OAAO,EAAE,MAAM,CAAA;CAChB,CAMA"}

package/dist/server.js

@@ -0,0 +1,10 @@
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { VERSION } from '@yourtechtribe-labs/koncept-core';
+export function createServer(opts) {
+    const mcp = new McpServer({
+        name: 'koncepto',
+        version: VERSION,
+    });
+    return { mcp, rootDir: opts.rootDir };
+}
+//# sourceMappingURL=server.js.map

package/dist/server.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"server.js","sourceRoot":"","sources":["../src/server.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,MAAM,yCAAyC,CAAA;AACnE,OAAO,EAAE,OAAO,EAAE,MAAM,kCAAkC,CAAA;AAM1D,MAAM,UAAU,YAAY,CAAC,IAAmB;IAI9C,MAAM,GAAG,GAAG,IAAI,SAAS,CAAC;QACxB,IAAI,EAAE,UAAU;QAChB,OAAO,EAAE,OAAO;KACjB,CAAC,CAAA;IACF,OAAO,EAAE,GAAG,EAAE,OAAO,EAAE,IAAI,CAAC,OAAO,EAAE,CAAA;AACvC,CAAC"}

package/dist/tools/_shared.d.ts

@@ -0,0 +1,3 @@
+export declare const KEBAB_ID_REGEX: RegExp;
+export declare function normalizePath(p: string): string;
+//# sourceMappingURL=_shared.d.ts.map

package/dist/tools/_shared.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"_shared.d.ts","sourceRoot":"","sources":["../../src/tools/_shared.ts"],"names":[],"mappings":"AAAA,eAAO,MAAM,cAAc,QAAsB,CAAA;AAEjD,wBAAgB,aAAa,CAAC,CAAC,EAAE,MAAM,GAAG,MAAM,CAE/C"}

package/dist/tools/_shared.js

@@ -0,0 +1,5 @@
+export const KEBAB_ID_REGEX = /^[a-z][a-z0-9-]+$/;
+export function normalizePath(p) {
+    return p.replace(/\\/g, '/').replace(/^\.\//, '');
+}
+//# sourceMappingURL=_shared.js.map

package/dist/tools/_shared.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"_shared.js","sourceRoot":"","sources":["../../src/tools/_shared.ts"],"names":[],"mappings":"AAAA,MAAM,CAAC,MAAM,cAAc,GAAG,mBAAmB,CAAA;AAEjD,MAAM,UAAU,aAAa,CAAC,CAAS;IACrC,OAAO,CAAC,CAAC,OAAO,CAAC,KAAK,EAAE,GAAG,CAAC,CAAC,OAAO,CAAC,OAAO,EAAE,EAAE,CAAC,CAAA;AACnD,CAAC"}

package/dist/tools/index.d.ts

@@ -0,0 +1,6 @@
+import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+export interface ToolContext {
+    rootDir: string;
+}
+export declare function registerAllTools(mcp: McpServer, ctx: ToolContext): void;
+//# sourceMappingURL=index.d.ts.map

package/dist/tools/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/tools/index.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,yCAAyC,CAAA;AAMxE,MAAM,WAAW,WAAW;IAC1B,OAAO,EAAE,MAAM,CAAA;CAChB;AAED,wBAAgB,gBAAgB,CAAC,GAAG,EAAE,SAAS,EAAE,GAAG,EAAE,WAAW,GAAG,IAAI,CAKvE"}

package/dist/tools/index.js

@@ -0,0 +1,11 @@
+import { registerKonceptGet } from './koncept-get.js';
+import { registerKonceptSearch } from './koncept-search.js';
+import { registerKonceptForFile } from './koncept-for-file.js';
+import { registerKonceptInvariantsAtScope } from './koncept-invariants-at-scope.js';
+export function registerAllTools(mcp, ctx) {
+    registerKonceptGet(mcp, ctx);
+    registerKonceptSearch(mcp, ctx);
+    registerKonceptForFile(mcp, ctx);
+    registerKonceptInvariantsAtScope(mcp, ctx);
+}
+//# sourceMappingURL=index.js.map

package/dist/tools/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/tools/index.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,kBAAkB,EAAE,MAAM,kBAAkB,CAAA;AACrD,OAAO,EAAE,qBAAqB,EAAE,MAAM,qBAAqB,CAAA;AAC3D,OAAO,EAAE,sBAAsB,EAAE,MAAM,uBAAuB,CAAA;AAC9D,OAAO,EAAE,gCAAgC,EAAE,MAAM,kCAAkC,CAAA;AAMnF,MAAM,UAAU,gBAAgB,CAAC,GAAc,EAAE,GAAgB;IAC/D,kBAAkB,CAAC,GAAG,EAAE,GAAG,CAAC,CAAA;IAC5B,qBAAqB,CAAC,GAAG,EAAE,GAAG,CAAC,CAAA;IAC/B,sBAAsB,CAAC,GAAG,EAAE,GAAG,CAAC,CAAA;IAChC,gCAAgC,CAAC,GAAG,EAAE,GAAG,CAAC,CAAA;AAC5C,CAAC"}

package/dist/tools/koncept-for-file.d.ts

@@ -0,0 +1,4 @@
+import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import type { ToolContext } from './index.js';
+export declare function registerKonceptForFile(mcp: McpServer, ctx: ToolContext): void;
+//# sourceMappingURL=koncept-for-file.d.ts.map

package/dist/tools/koncept-for-file.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"koncept-for-file.d.ts","sourceRoot":"","sources":["../../src/tools/koncept-for-file.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,yCAAyC,CAAA;AAOxE,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,YAAY,CAAA;AAiB7C,wBAAgB,sBAAsB,CAAC,GAAG,EAAE,SAAS,EAAE,GAAG,EAAE,WAAW,GAAG,IAAI,CAyC7E"}

package/dist/tools/koncept-for-file.js

@@ -0,0 +1,47 @@
+import { z } from 'zod';
+import { ConceptTypeEnum, RoleEnum, indexConcepts, parseConceptFile, } from '@yourtechtribe-labs/koncept-core';
+import { normalizePath } from './_shared.js';
+const inputSchema = { path: z.string().min(1) };
+const outputSchema = {
+    matches: z.array(z.object({
+        id: z.string(),
+        name: z.string(),
+        type: ConceptTypeEnum,
+        role: RoleEnum,
+        purpose: z.string(),
+    })),
+};
+export function registerKonceptForFile(mcp, ctx) {
+    mcp.registerTool('koncept_for_file', {
+        title: 'Concepts for file',
+        description: 'List concepts that participate in a given file path. Returns each concept with its role and purpose for that file.',
+        inputSchema,
+        outputSchema,
+        annotations: { readOnlyHint: true, idempotentHint: true },
+    }, async ({ path: target }) => {
+        const normalized = normalizePath(target);
+        const index = await indexConcepts(ctx.rootDir);
+        const candidates = index.entries.filter((e) => e.participants_paths.some((p) => normalizePath(p) === normalized));
+        const matches = await Promise.all(candidates.map(async (entry) => {
+            const parsed = await parseConceptFile(entry.file);
+            if (!parsed.concept)
+                return null;
+            const part = parsed.concept.participants.find((p) => normalizePath(p.file) === normalized);
+            if (!part)
+                return null;
+            return {
+                id: entry.id,
+                name: entry.name,
+                type: entry.type,
+                role: part.role,
+                purpose: part.purpose,
+            };
+        }));
+        const payload = { matches: matches.filter((m) => m !== null) };
+        return {
+            content: [{ type: 'text', text: JSON.stringify(payload, null, 2) }],
+            structuredContent: payload,
+        };
+    });
+}
+//# sourceMappingURL=koncept-for-file.js.map

package/dist/tools/koncept-for-file.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"koncept-for-file.js","sourceRoot":"","sources":["../../src/tools/koncept-for-file.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAA;AAEvB,OAAO,EACL,eAAe,EACf,QAAQ,EACR,aAAa,EACb,gBAAgB,GACjB,MAAM,kCAAkC,CAAA;AAEzC,OAAO,EAAE,aAAa,EAAE,MAAM,cAAc,CAAA;AAE5C,MAAM,WAAW,GAAG,EAAE,IAAI,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,CAAA;AAE/C,MAAM,YAAY,GAAG;IACnB,OAAO,EAAE,CAAC,CAAC,KAAK,CACd,CAAC,CAAC,MAAM,CAAC;QACP,EAAE,EAAE,CAAC,CAAC,MAAM,EAAE;QACd,IAAI,EAAE,CAAC,CAAC,MAAM,EAAE;QAChB,IAAI,EAAE,eAAe;QACrB,IAAI,EAAE,QAAQ;QACd,OAAO,EAAE,CAAC,CAAC,MAAM,EAAE;KACpB,CAAC,CACH;CACF,CAAA;AAED,MAAM,UAAU,sBAAsB,CAAC,GAAc,EAAE,GAAgB;IACrE,GAAG,CAAC,YAAY,CACd,kBAAkB,EAClB;QACE,KAAK,EAAE,mBAAmB;QAC1B,WAAW,EACT,oHAAoH;QACtH,WAAW;QACX,YAAY;QACZ,WAAW,EAAE,EAAE,YAAY,EAAE,IAAI,EAAE,cAAc,EAAE,IAAI,EAAE;KAC1D,EACD,KAAK,EAAE,EAAE,IAAI,EAAE,MAAM,EAAE,EAAE,EAAE;QACzB,MAAM,UAAU,GAAG,aAAa,CAAC,MAAM,CAAC,CAAA;QACxC,MAAM,KAAK,GAAG,MAAM,aAAa,CAAC,GAAG,CAAC,OAAO,CAAC,CAAA;QAC9C,MAAM,UAAU,GAAG,KAAK,CAAC,OAAO,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAC5C,CAAC,CAAC,kBAAkB,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,aAAa,CAAC,CAAC,CAAC,KAAK,UAAU,CAAC,CAClE,CAAA;QACD,MAAM,OAAO,GAAG,MAAM,OAAO,CAAC,GAAG,CAC/B,UAAU,CAAC,GAAG,CAAC,KAAK,EAAE,KAAK,EAAE,EAAE;YAC7B,MAAM,MAAM,GAAG,MAAM,gBAAgB,CAAC,KAAK,CAAC,IAAI,CAAC,CAAA;YACjD,IAAI,CAAC,MAAM,CAAC,OAAO;gBAAE,OAAO,IAAI,CAAA;YAChC,MAAM,IAAI,GAAG,MAAM,CAAC,OAAO,CAAC,YAAY,CAAC,IAAI,CAC3C,CAAC,CAAmB,EAAE,EAAE,CAAC,aAAa,CAAC,CAAC,CAAC,IAAI,CAAC,KAAK,UAAU,CAC9D,CAAA;YACD,IAAI,CAAC,IAAI;gBAAE,OAAO,IAAI,CAAA;YACtB,OAAO;gBACL,EAAE,EAAE,KAAK,CAAC,EAAE;gBACZ,IAAI,EAAE,KAAK,CAAC,IAAI;gBAChB,IAAI,EAAE,KAAK,CAAC,IAAI;gBAChB,IAAI,EAAE,IAAI,CAAC,IAAI;gBACf,OAAO,EAAE,IAAI,CAAC,OAAO;aACtB,CAAA;QACH,CAAC,CAAC,CACH,CAAA;QACD,MAAM,OAAO,GAAG,EAAE,OAAO,EAAE,OAAO,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,KAAK,IAAI,CAAC,EAAE,CAAA;QAC9D,OAAO;YACL,OAAO,EAAE,CAAC,EAAE,IAAI,EAAE,MAAe,EAAE,IAAI,EAAE,IAAI,CAAC,SAAS,CAAC,OAAO,EAAE,IAAI,EAAE,CAAC,CAAC,EAAE,CAAC;YAC5E,iBAAiB,EAAE,OAAO;SAC3B,CAAA;IACH,CAAC,CACF,CAAA;AACH,CAAC"}

package/dist/tools/koncept-get.d.ts

@@ -0,0 +1,4 @@
+import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import type { ToolContext } from './index.js';
+export declare function registerKonceptGet(mcp: McpServer, ctx: ToolContext): void;
+//# sourceMappingURL=koncept-get.d.ts.map

package/dist/tools/koncept-get.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"koncept-get.d.ts","sourceRoot":"","sources":["../../src/tools/koncept-get.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,yCAAyC,CAAA;AAMxE,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,YAAY,CAAA;AAY7C,wBAAgB,kBAAkB,CAAC,GAAG,EAAE,SAAS,EAAE,GAAG,EAAE,WAAW,GAAG,IAAI,CAiCzE"}

package/dist/tools/koncept-get.js

@@ -0,0 +1,47 @@
+import { z } from 'zod';
+import { ConceptSchema, indexConcepts, parseConceptFile, } from '@yourtechtribe-labs/koncept-core';
+import { KEBAB_ID_REGEX } from './_shared.js';
+const inputSchema = { id: z.string().min(1) };
+const outputSchema = {
+    concept: ConceptSchema.optional(),
+    error: z.enum(['not_found', 'invalid_id', 'parse_failed']).optional(),
+    id: z.string().optional(),
+    reason: z.string().optional(),
+};
+export function registerKonceptGet(mcp, ctx) {
+    mcp.registerTool('koncept_get', {
+        title: 'Get concept by id',
+        description: 'Fetch a concept document by its kebab-case id. Returns the full Concept (purpose, participants, invariants, related_concepts).',
+        inputSchema,
+        outputSchema,
+        annotations: { readOnlyHint: true, idempotentHint: true },
+    }, async ({ id }) => {
+        if (!KEBAB_ID_REGEX.test(id))
+            return errorResult({ error: 'invalid_id', id });
+        const index = await indexConcepts(ctx.rootDir);
+        const entry = index.entries.find((e) => e.id === id);
+        if (!entry)
+            return errorResult({ error: 'not_found', id });
+        const parsed = await parseConceptFile(entry.file);
+        if (!parsed.concept) {
+            return errorResult({
+                error: 'parse_failed',
+                id,
+                reason: parsed.errors[0]?.type ?? 'unknown',
+            });
+        }
+        const payload = { concept: parsed.concept };
+        return {
+            content: [{ type: 'text', text: JSON.stringify(payload, null, 2) }],
+            structuredContent: payload,
+        };
+    });
+}
+function errorResult(payload) {
+    return {
+        content: [{ type: 'text', text: JSON.stringify(payload, null, 2) }],
+        structuredContent: payload,
+        isError: true,
+    };
+}
+//# sourceMappingURL=koncept-get.js.map

package/dist/tools/koncept-get.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"koncept-get.js","sourceRoot":"","sources":["../../src/tools/koncept-get.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAA;AAEvB,OAAO,EACL,aAAa,EACb,aAAa,EACb,gBAAgB,GACjB,MAAM,kCAAkC,CAAA;AAEzC,OAAO,EAAE,cAAc,EAAE,MAAM,cAAc,CAAA;AAE7C,MAAM,WAAW,GAAG,EAAE,EAAE,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,CAAA;AAE7C,MAAM,YAAY,GAAG;IACnB,OAAO,EAAE,aAAa,CAAC,QAAQ,EAAE;IACjC,KAAK,EAAE,CAAC,CAAC,IAAI,CAAC,CAAC,WAAW,EAAE,YAAY,EAAE,cAAc,CAAC,CAAC,CAAC,QAAQ,EAAE;IACrE,EAAE,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE;IACzB,MAAM,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE;CAC9B,CAAA;AAED,MAAM,UAAU,kBAAkB,CAAC,GAAc,EAAE,GAAgB;IACjE,GAAG,CAAC,YAAY,CACd,aAAa,EACb;QACE,KAAK,EAAE,mBAAmB;QAC1B,WAAW,EACT,gIAAgI;QAClI,WAAW;QACX,YAAY;QACZ,WAAW,EAAE,EAAE,YAAY,EAAE,IAAI,EAAE,cAAc,EAAE,IAAI,EAAE;KAC1D,EACD,KAAK,EAAE,EAAE,EAAE,EAAE,EAAE,EAAE;QACf,IAAI,CAAC,cAAc,CAAC,IAAI,CAAC,EAAE,CAAC;YAAE,OAAO,WAAW,CAAC,EAAE,KAAK,EAAE,YAAY,EAAE,EAAE,EAAE,CAAC,CAAA;QAE7E,MAAM,KAAK,GAAG,MAAM,aAAa,CAAC,GAAG,CAAC,OAAO,CAAC,CAAA;QAC9C,MAAM,KAAK,GAAG,KAAK,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,EAAE,KAAK,EAAE,CAAC,CAAA;QACpD,IAAI,CAAC,KAAK;YAAE,OAAO,WAAW,CAAC,EAAE,KAAK,EAAE,WAAW,EAAE,EAAE,EAAE,CAAC,CAAA;QAE1D,MAAM,MAAM,GAAG,MAAM,gBAAgB,CAAC,KAAK,CAAC,IAAI,CAAC,CAAA;QACjD,IAAI,CAAC,MAAM,CAAC,OAAO,EAAE,CAAC;YACpB,OAAO,WAAW,CAAC;gBACjB,KAAK,EAAE,cAAc;gBACrB,EAAE;gBACF,MAAM,EAAE,MAAM,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,IAAI,IAAI,SAAS;aAC5C,CAAC,CAAA;QACJ,CAAC;QACD,MAAM,OAAO,GAAG,EAAE,OAAO,EAAE,MAAM,CAAC,OAAO,EAAE,CAAA;QAC3C,OAAO;YACL,OAAO,EAAE,CAAC,EAAE,IAAI,EAAE,MAAe,EAAE,IAAI,EAAE,IAAI,CAAC,SAAS,CAAC,OAAO,EAAE,IAAI,EAAE,CAAC,CAAC,EAAE,CAAC;YAC5E,iBAAiB,EAAE,OAAO;SAC3B,CAAA;IACH,CAAC,CACF,CAAA;AACH,CAAC;AAED,SAAS,WAAW,CAAC,OAA+B;IAClD,OAAO;QACL,OAAO,EAAE,CAAC,EAAE,IAAI,EAAE,MAAe,EAAE,IAAI,EAAE,IAAI,CAAC,SAAS,CAAC,OAAO,EAAE,IAAI,EAAE,CAAC,CAAC,EAAE,CAAC;QAC5E,iBAAiB,EAAE,OAAO;QAC1B,OAAO,EAAE,IAAI;KACd,CAAA;AACH,CAAC"}

package/dist/tools/koncept-invariants-at-scope.d.ts

@@ -0,0 +1,4 @@
+import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import type { ToolContext } from './index.js';
+export declare function registerKonceptInvariantsAtScope(mcp: McpServer, ctx: ToolContext): void;
+//# sourceMappingURL=koncept-invariants-at-scope.d.ts.map

package/dist/tools/koncept-invariants-at-scope.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"koncept-invariants-at-scope.d.ts","sourceRoot":"","sources":["../../src/tools/koncept-invariants-at-scope.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,yCAAyC,CAAA;AAMxE,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,YAAY,CAAA;AAiB7C,wBAAgB,gCAAgC,CAC9C,GAAG,EAAE,SAAS,EACd,GAAG,EAAE,WAAW,GACf,IAAI,CA6CN"}

package/dist/tools/koncept-invariants-at-scope.js

@@ -0,0 +1,49 @@
+import { z } from 'zod';
+import { SeverityEnum, indexConcepts, parseConceptFile, } from '@yourtechtribe-labs/koncept-core';
+import { KEBAB_ID_REGEX, normalizePath } from './_shared.js';
+const inputSchema = { scope: z.string().min(1) };
+const outputSchema = {
+    invariants: z.array(z.object({
+        concept_id: z.string(),
+        invariant_id: z.string(),
+        description: z.string(),
+        severity: SeverityEnum,
+        source_file: z.string(),
+    })),
+};
+export function registerKonceptInvariantsAtScope(mcp, ctx) {
+    mcp.registerTool('koncept_invariants_at_scope', {
+        title: 'Invariants at scope',
+        description: 'List invariants that apply within a scope. Scope can be a file path or a concept id (kebab-case).',
+        inputSchema,
+        outputSchema,
+        annotations: { readOnlyHint: true, idempotentHint: true },
+    }, async ({ scope }) => {
+        const index = await indexConcepts(ctx.rootDir);
+        const isConceptId = KEBAB_ID_REGEX.test(scope);
+        const target = isConceptId ? null : normalizePath(scope);
+        const conceptsToInspect = isConceptId
+            ? index.entries.filter((e) => e.id === scope)
+            : index.entries.filter((e) => e.participants_paths.some((p) => normalizePath(p) === target));
+        const parsedAll = await Promise.all(conceptsToInspect.map((e) => parseConceptFile(e.file)));
+        const invariants = parsedAll.flatMap((parsed, i) => {
+            if (!parsed.concept)
+                return [];
+            const concept = parsed.concept;
+            const sourceFile = conceptsToInspect[i].file;
+            return concept.invariants.map((inv) => ({
+                concept_id: concept.id,
+                invariant_id: inv.id,
+                description: inv.description,
+                severity: inv.severity,
+                source_file: sourceFile,
+            }));
+        });
+        const payload = { invariants };
+        return {
+            content: [{ type: 'text', text: JSON.stringify(payload, null, 2) }],
+            structuredContent: payload,
+        };
+    });
+}
+//# sourceMappingURL=koncept-invariants-at-scope.js.map

package/dist/tools/koncept-invariants-at-scope.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"koncept-invariants-at-scope.js","sourceRoot":"","sources":["../../src/tools/koncept-invariants-at-scope.ts"],"names":[],"mappings":"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"}

package/dist/tools/koncept-search.d.ts

@@ -0,0 +1,4 @@
+import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import type { ToolContext } from './index.js';
+export declare function registerKonceptSearch(mcp: McpServer, ctx: ToolContext): void;
+//# sourceMappingURL=koncept-search.d.ts.map

package/dist/tools/koncept-search.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"koncept-search.d.ts","sourceRoot":"","sources":["../../src/tools/koncept-search.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,yCAAyC,CAAA;AAMxE,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,YAAY,CAAA;AAmB7C,wBAAgB,qBAAqB,CAAC,GAAG,EAAE,SAAS,EAAE,GAAG,EAAE,WAAW,GAAG,IAAI,CA6B5E"}

package/dist/tools/koncept-search.js

@@ -0,0 +1,41 @@
+import { z } from 'zod';
+import { ConceptTypeEnum, indexConcepts, searchEntries, } from '@yourtechtribe-labs/koncept-core';
+const inputSchema = {
+    query: z.string().min(1),
+    limit: z.number().int().positive().max(50).optional(),
+};
+const outputSchema = {
+    matches: z.array(z.object({
+        id: z.string(),
+        name: z.string(),
+        type: ConceptTypeEnum,
+        score: z.number(),
+        matched_on: z.array(z.enum(['id', 'name', 'tags'])),
+    })),
+};
+export function registerKonceptSearch(mcp, ctx) {
+    mcp.registerTool('koncept_search', {
+        title: 'Search concepts',
+        description: 'Fuzzy-search concepts by id/name/tag. Returns ranked matches with score and which fields matched.',
+        inputSchema,
+        outputSchema,
+        annotations: { readOnlyHint: true, idempotentHint: true },
+    }, async ({ query, limit }) => {
+        const index = await indexConcepts(ctx.rootDir);
+        const hits = searchEntries(index.entries, query, limit ?? 10);
+        const payload = {
+            matches: hits.map((h) => ({
+                id: h.entry.id,
+                name: h.entry.name,
+                type: h.entry.type,
+                score: h.score,
+                matched_on: h.matchedOn,
+            })),
+        };
+        return {
+            content: [{ type: 'text', text: JSON.stringify(payload, null, 2) }],
+            structuredContent: payload,
+        };
+    });
+}
+//# sourceMappingURL=koncept-search.js.map

package/dist/tools/koncept-search.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"koncept-search.js","sourceRoot":"","sources":["../../src/tools/koncept-search.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAA;AAEvB,OAAO,EACL,eAAe,EACf,aAAa,EACb,aAAa,GACd,MAAM,kCAAkC,CAAA;AAGzC,MAAM,WAAW,GAAG;IAClB,KAAK,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC;IACxB,KAAK,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,EAAE,CAAC,QAAQ,EAAE,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC,QAAQ,EAAE;CACtD,CAAA;AAED,MAAM,YAAY,GAAG;IACnB,OAAO,EAAE,CAAC,CAAC,KAAK,CACd,CAAC,CAAC,MAAM,CAAC;QACP,EAAE,EAAE,CAAC,CAAC,MAAM,EAAE;QACd,IAAI,EAAE,CAAC,CAAC,MAAM,EAAE;QAChB,IAAI,EAAE,eAAe;QACrB,KAAK,EAAE,CAAC,CAAC,MAAM,EAAE;QACjB,UAAU,EAAE,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,IAAI,EAAE,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC;KACpD,CAAC,CACH;CACF,CAAA;AAED,MAAM,UAAU,qBAAqB,CAAC,GAAc,EAAE,GAAgB;IACpE,GAAG,CAAC,YAAY,CACd,gBAAgB,EAChB;QACE,KAAK,EAAE,iBAAiB;QACxB,WAAW,EACT,mGAAmG;QACrG,WAAW;QACX,YAAY;QACZ,WAAW,EAAE,EAAE,YAAY,EAAE,IAAI,EAAE,cAAc,EAAE,IAAI,EAAE;KAC1D,EACD,KAAK,EAAE,EAAE,KAAK,EAAE,KAAK,EAAE,EAAE,EAAE;QACzB,MAAM,KAAK,GAAG,MAAM,aAAa,CAAC,GAAG,CAAC,OAAO,CAAC,CAAA;QAC9C,MAAM,IAAI,GAAG,aAAa,CAAC,KAAK,CAAC,OAAO,EAAE,KAAK,EAAE,KAAK,IAAI,EAAE,CAAC,CAAA;QAC7D,MAAM,OAAO,GAAG;YACd,OAAO,EAAE,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC;gBACxB,EAAE,EAAE,CAAC,CAAC,KAAK,CAAC,EAAE;gBACd,IAAI,EAAE,CAAC,CAAC,KAAK,CAAC,IAAI;gBAClB,IAAI,EAAE,CAAC,CAAC,KAAK,CAAC,IAAI;gBAClB,KAAK,EAAE,CAAC,CAAC,KAAK;gBACd,UAAU,EAAE,CAAC,CAAC,SAAS;aACxB,CAAC,CAAC;SACJ,CAAA;QACD,OAAO;YACL,OAAO,EAAE,CAAC,EAAE,IAAI,EAAE,MAAe,EAAE,IAAI,EAAE,IAAI,CAAC,SAAS,CAAC,OAAO,EAAE,IAAI,EAAE,CAAC,CAAC,EAAE,CAAC;YAC5E,iBAAiB,EAAE,OAAO;SAC3B,CAAA;IACH,CAAC,CACF,CAAA;AACH,CAAC"}

package/package.json

@@ -0,0 +1,38 @@
+{
+  "name": "@yourtechtribe-labs/koncept-mcp-server",
+  "version": "0.1.0-alpha.1",
+  "description": "MCP server exposing semantic concept graph tools (koncept_get, koncept_for_file, koncept_search, koncept_invariants_at_scope).",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "bin": {
+    "koncept-mcp": "./dist/index.js"
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "1.29.0",
+    "@yourtechtribe-labs/koncept-core": "^0.1.0-alpha.1",
+    "zod": "4.4.2"
+  },
+  "publishConfig": {
+    "access": "public",
+    "tag": "alpha"
+  },
+  "license": "MIT",
+  "homepage": "https://github.com/yourtechtribe-labs/koncept-mcp",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/yourtechtribe-labs/koncept-mcp",
+    "directory": "packages/koncept-mcp-server"
+  },
+  "scripts": {
+    "build": "tsc",
+    "test": "vitest run",
+    "lint": "echo 'lint stub'",
+    "clean": "rm -rf dist",
+    "start": "node dist/index.js"
+  }
+}