@pithyjs/mcp 0.0.0-stage → 0.1.0-beta.2
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/LICENSE +21 -0
- package/README.md +223 -2
- package/dist/cli.d.ts +3 -0
- package/dist/cli.js +74 -0
- package/dist/errors/catalog.d.ts +48 -0
- package/dist/errors/catalog.js +252 -0
- package/dist/guard.d.ts +41 -0
- package/dist/guard.js +140 -0
- package/dist/index.d.ts +4 -0
- package/dist/index.js +4 -0
- package/dist/knowledge.d.ts +157 -0
- package/dist/knowledge.js +163 -0
- package/dist/lookup.d.ts +47 -0
- package/dist/lookup.js +69 -0
- package/dist/pidl.d.ts +27 -0
- package/dist/pidl.js +251 -0
- package/dist/scaffold.d.ts +54 -0
- package/dist/scaffold.js +280 -0
- package/dist/search.d.ts +37 -0
- package/dist/search.js +129 -0
- package/dist/server.d.ts +25 -0
- package/dist/server.js +126 -0
- package/dist/snapshot.json +1 -0
- package/dist/template.d.ts +26 -0
- package/dist/template.js +66 -0
- package/dist/tokens.d.ts +71 -0
- package/dist/tokens.js +420 -0
- package/package.json +56 -3
package/dist/guard.d.ts
ADDED
|
@@ -0,0 +1,41 @@
|
|
|
1
|
+
/** @codex { "id": "pithy.mcp.guard", "title": "MCP Input Guard", "category": "feature", "risk": "high" } */
|
|
2
|
+
import type { Transport } from '@modelcontextprotocol/sdk/shared/transport.js';
|
|
3
|
+
/** @codexApi {"parent":"pithy.mcp.guard","name":"GuardLimits","stability":"experimental","signature":"interface GuardLimits { maxDepth: number; maxValues: number; maxChars: number }"} */
|
|
4
|
+
/** The bounds {@link guardInput} enforces. */
|
|
5
|
+
export interface GuardLimits {
|
|
6
|
+
/** Deepest nesting of objects and arrays. */
|
|
7
|
+
maxDepth: number;
|
|
8
|
+
/** Most values, counting every object, array and primitive. */
|
|
9
|
+
maxValues: number;
|
|
10
|
+
/** Most characters, summed over every string and key. */
|
|
11
|
+
maxChars: number;
|
|
12
|
+
}
|
|
13
|
+
/** @codexApi {"parent":"pithy.mcp.guard","name":"GuardError","stability":"experimental","signature":"class GuardError extends Error"} */
|
|
14
|
+
/** Thrown by {@link guardInput}; the message names the offending path. */
|
|
15
|
+
export declare class GuardError extends Error {
|
|
16
|
+
name: string;
|
|
17
|
+
}
|
|
18
|
+
/**
|
|
19
|
+
* Rejects a value that is not plain JSON data, before any schema parses it.
|
|
20
|
+
*
|
|
21
|
+
* Forbids own keys `__proto__`, `constructor` and `prototype` at any depth,
|
|
22
|
+
* symbol keys and values, functions, and objects other than plain objects and
|
|
23
|
+
* arrays, and caps depth, value count and total characters.
|
|
24
|
+
*
|
|
25
|
+
* @param value - Raw tool arguments.
|
|
26
|
+
* @param limits - The bounds to hold `value` to.
|
|
27
|
+
* @throws {GuardError} On the first violation found.
|
|
28
|
+
*/
|
|
29
|
+
/** @codexApi {"parent":"pithy.mcp.guard","name":"guardInput","stability":"experimental","signature":"(value: unknown, limits?: GuardLimits) => void"} */
|
|
30
|
+
export declare function guardInput(value: unknown, limits?: GuardLimits): void;
|
|
31
|
+
/**
|
|
32
|
+
* Wraps a transport so that every `tools/call` (and `resources/read`) is run
|
|
33
|
+
* through {@link guardInput} as it arrives, before the SDK's schemas parse
|
|
34
|
+
* it. A rejected request is answered with JSON-RPC error -32602 and is never
|
|
35
|
+
* passed on.
|
|
36
|
+
*
|
|
37
|
+
* @param inner - The transport to read from.
|
|
38
|
+
* @returns A transport to hand to `McpServer.connect`.
|
|
39
|
+
*/
|
|
40
|
+
/** @codexApi {"parent":"pithy.mcp.guard","name":"guardTransport","stability":"experimental","signature":"(inner: Transport) => Transport"} */
|
|
41
|
+
export declare function guardTransport(inner: Transport): Transport;
|
package/dist/guard.js
ADDED
|
@@ -0,0 +1,140 @@
|
|
|
1
|
+
/** @codex { "id": "pithy.mcp.guard", "title": "MCP Input Guard", "category": "feature", "risk": "high" } */
|
|
2
|
+
const FORBIDDEN_KEYS = new Set(['__proto__', 'constructor', 'prototype']);
|
|
3
|
+
// The limits every tool call is held to.
|
|
4
|
+
const DEFAULT_GUARD_LIMITS = {
|
|
5
|
+
maxDepth: 32,
|
|
6
|
+
maxValues: 20_000,
|
|
7
|
+
maxChars: 2_000_000,
|
|
8
|
+
};
|
|
9
|
+
/** @codexApi {"parent":"pithy.mcp.guard","name":"GuardError","stability":"experimental","signature":"class GuardError extends Error"} */
|
|
10
|
+
/** Thrown by {@link guardInput}; the message names the offending path. */
|
|
11
|
+
export class GuardError extends Error {
|
|
12
|
+
name = 'GuardError';
|
|
13
|
+
}
|
|
14
|
+
const isPlain = (v) => {
|
|
15
|
+
const proto = Object.getPrototypeOf(v);
|
|
16
|
+
return proto === Object.prototype || proto === null;
|
|
17
|
+
};
|
|
18
|
+
/**
|
|
19
|
+
* Rejects a value that is not plain JSON data, before any schema parses it.
|
|
20
|
+
*
|
|
21
|
+
* Forbids own keys `__proto__`, `constructor` and `prototype` at any depth,
|
|
22
|
+
* symbol keys and values, functions, and objects other than plain objects and
|
|
23
|
+
* arrays, and caps depth, value count and total characters.
|
|
24
|
+
*
|
|
25
|
+
* @param value - Raw tool arguments.
|
|
26
|
+
* @param limits - The bounds to hold `value` to.
|
|
27
|
+
* @throws {GuardError} On the first violation found.
|
|
28
|
+
*/
|
|
29
|
+
/** @codexApi {"parent":"pithy.mcp.guard","name":"guardInput","stability":"experimental","signature":"(value: unknown, limits?: GuardLimits) => void"} */
|
|
30
|
+
export function guardInput(value, limits = DEFAULT_GUARD_LIMITS) {
|
|
31
|
+
let values = 0;
|
|
32
|
+
let chars = 0;
|
|
33
|
+
const fail = (path, why) => {
|
|
34
|
+
throw new GuardError(`${path || 'arguments'}: ${why}`);
|
|
35
|
+
};
|
|
36
|
+
const visit = (v, path, depth) => {
|
|
37
|
+
if (++values > limits.maxValues)
|
|
38
|
+
fail('arguments', `more than ${limits.maxValues} values`);
|
|
39
|
+
switch (typeof v) {
|
|
40
|
+
case 'string':
|
|
41
|
+
chars += v.length;
|
|
42
|
+
if (chars > limits.maxChars)
|
|
43
|
+
fail('arguments', `more than ${limits.maxChars} characters`);
|
|
44
|
+
return;
|
|
45
|
+
case 'number':
|
|
46
|
+
case 'boolean':
|
|
47
|
+
case 'undefined':
|
|
48
|
+
return;
|
|
49
|
+
case 'function':
|
|
50
|
+
return fail(path, 'a function is not allowed');
|
|
51
|
+
case 'symbol':
|
|
52
|
+
return fail(path, 'a symbol is not allowed');
|
|
53
|
+
case 'bigint':
|
|
54
|
+
return fail(path, 'a bigint is not allowed');
|
|
55
|
+
}
|
|
56
|
+
if (v === null)
|
|
57
|
+
return;
|
|
58
|
+
if (depth > limits.maxDepth)
|
|
59
|
+
fail(path, `nested deeper than depth ${limits.maxDepth}`);
|
|
60
|
+
const obj = v;
|
|
61
|
+
if (Array.isArray(obj)) {
|
|
62
|
+
if (Object.getPrototypeOf(obj) !== Array.prototype)
|
|
63
|
+
fail(path, 'not a plain array');
|
|
64
|
+
obj.forEach((item, i) => visit(item, `${path}[${i}]`, depth + 1));
|
|
65
|
+
return;
|
|
66
|
+
}
|
|
67
|
+
if (!isPlain(obj))
|
|
68
|
+
fail(path, 'not a plain object');
|
|
69
|
+
if (Object.getOwnPropertySymbols(obj).length > 0)
|
|
70
|
+
fail(path, 'a symbol key is not allowed');
|
|
71
|
+
for (const key of Object.getOwnPropertyNames(obj)) {
|
|
72
|
+
const at = path ? `${path}.${key}` : key;
|
|
73
|
+
if (FORBIDDEN_KEYS.has(key))
|
|
74
|
+
fail(at, `the key "${key}" is not allowed`);
|
|
75
|
+
chars += key.length;
|
|
76
|
+
if (chars > limits.maxChars)
|
|
77
|
+
fail('arguments', `more than ${limits.maxChars} characters`);
|
|
78
|
+
visit(obj[key], at, depth + 1);
|
|
79
|
+
}
|
|
80
|
+
};
|
|
81
|
+
visit(value, '', 0);
|
|
82
|
+
}
|
|
83
|
+
/** The raw payload of a request this server guards, or `undefined`. */
|
|
84
|
+
function guardedPayload(msg) {
|
|
85
|
+
const params = msg.params;
|
|
86
|
+
if (msg.method === 'tools/call')
|
|
87
|
+
return { value: params?.arguments };
|
|
88
|
+
if (msg.method === 'resources/read')
|
|
89
|
+
return { value: params };
|
|
90
|
+
return undefined;
|
|
91
|
+
}
|
|
92
|
+
/**
|
|
93
|
+
* Wraps a transport so that every `tools/call` (and `resources/read`) is run
|
|
94
|
+
* through {@link guardInput} as it arrives, before the SDK's schemas parse
|
|
95
|
+
* it. A rejected request is answered with JSON-RPC error -32602 and is never
|
|
96
|
+
* passed on.
|
|
97
|
+
*
|
|
98
|
+
* @param inner - The transport to read from.
|
|
99
|
+
* @returns A transport to hand to `McpServer.connect`.
|
|
100
|
+
*/
|
|
101
|
+
/** @codexApi {"parent":"pithy.mcp.guard","name":"guardTransport","stability":"experimental","signature":"(inner: Transport) => Transport"} */
|
|
102
|
+
export function guardTransport(inner) {
|
|
103
|
+
const outer = {
|
|
104
|
+
start: () => inner.start(),
|
|
105
|
+
send: (message, options) => inner.send(message, options),
|
|
106
|
+
close: () => inner.close(),
|
|
107
|
+
get sessionId() {
|
|
108
|
+
return inner.sessionId;
|
|
109
|
+
},
|
|
110
|
+
};
|
|
111
|
+
if (inner.setProtocolVersion) {
|
|
112
|
+
outer.setProtocolVersion = version => inner.setProtocolVersion?.(version);
|
|
113
|
+
}
|
|
114
|
+
inner.onclose = () => outer.onclose?.();
|
|
115
|
+
inner.onerror = error => outer.onerror?.(error);
|
|
116
|
+
inner.onmessage = (message, extra) => {
|
|
117
|
+
const payload = guardedPayload(message);
|
|
118
|
+
if (payload) {
|
|
119
|
+
try {
|
|
120
|
+
guardInput(payload.value);
|
|
121
|
+
}
|
|
122
|
+
catch (e) {
|
|
123
|
+
if (!(e instanceof GuardError))
|
|
124
|
+
throw e;
|
|
125
|
+
const id = message.id;
|
|
126
|
+
if (typeof id === 'string' || typeof id === 'number') {
|
|
127
|
+
const reply = {
|
|
128
|
+
jsonrpc: '2.0',
|
|
129
|
+
id,
|
|
130
|
+
error: { code: -32602, message: `Rejected input: ${e.message}` },
|
|
131
|
+
};
|
|
132
|
+
void inner.send(reply);
|
|
133
|
+
}
|
|
134
|
+
return;
|
|
135
|
+
}
|
|
136
|
+
}
|
|
137
|
+
outer.onmessage?.(message, extra);
|
|
138
|
+
};
|
|
139
|
+
return outer;
|
|
140
|
+
}
|
package/dist/index.d.ts
ADDED
|
@@ -0,0 +1,4 @@
|
|
|
1
|
+
/** @codex { "id": "pithy.mcp", "title": "@pithyjs/mcp", "category": "feature", "risk": "medium" } */
|
|
2
|
+
export { connectPithyServer, createPithyServer, TOOL_NAMES } from './server.js';
|
|
3
|
+
export { buildKnowledge, findRepoRoot, loadSnapshot, type Citation, type Knowledge, type KnowledgeApi, type KnowledgeComponent, type KnowledgeEntry, type KnowledgeExample, type KnowledgeScope, } from './knowledge.js';
|
|
4
|
+
export { GuardError, guardInput, guardTransport, type GuardLimits, } from './guard.js';
|
package/dist/index.js
ADDED
|
@@ -0,0 +1,4 @@
|
|
|
1
|
+
/** @codex { "id": "pithy.mcp", "title": "@pithyjs/mcp", "category": "feature", "risk": "medium" } */
|
|
2
|
+
export { connectPithyServer, createPithyServer, TOOL_NAMES } from './server.js';
|
|
3
|
+
export { buildKnowledge, findRepoRoot, loadSnapshot, } from './knowledge.js';
|
|
4
|
+
export { GuardError, guardInput, guardTransport, } from './guard.js';
|
|
@@ -0,0 +1,157 @@
|
|
|
1
|
+
/** @codex { "id": "pithy.mcp.knowledge", "title": "MCP Knowledge Model", "category": "feature", "risk": "medium" } */
|
|
2
|
+
/** @codexApi {"parent":"pithy.mcp.knowledge","name":"KnowledgeScope","stability":"experimental","signature":"type KnowledgeScope = 'public' | 'all'"} */
|
|
3
|
+
/** `public`: published packages only. `all`: every package in the checkout. */
|
|
4
|
+
export type KnowledgeScope = 'public' | 'all';
|
|
5
|
+
/** @codexApi {"parent":"pithy.mcp.knowledge","name":"Citation","stability":"experimental","signature":"interface Citation { entryId?: string; file: string; line?: number }"} */
|
|
6
|
+
/** Where an answer comes from: a repo-relative file, and the line when known. */
|
|
7
|
+
export interface Citation {
|
|
8
|
+
entryId?: string;
|
|
9
|
+
file: string;
|
|
10
|
+
line?: number;
|
|
11
|
+
}
|
|
12
|
+
/** @codexApi {"parent":"pithy.mcp.knowledge","name":"SourcePlace","stability":"experimental","signature":"interface SourcePlace { pkg: string; file: string; line: number }"} */
|
|
13
|
+
/** An annotation's package, repo-relative file and line. */
|
|
14
|
+
export interface SourcePlace {
|
|
15
|
+
pkg: string;
|
|
16
|
+
file: string;
|
|
17
|
+
line: number;
|
|
18
|
+
}
|
|
19
|
+
/** @codexApi {"parent":"pithy.mcp.knowledge","name":"KnowledgeApi","stability":"experimental","signature":"interface KnowledgeApi"} */
|
|
20
|
+
/** One `@codexApi`, joined with the declaration it annotates. */
|
|
21
|
+
export interface KnowledgeApi {
|
|
22
|
+
name: string;
|
|
23
|
+
stability: string | null;
|
|
24
|
+
signature: string | null;
|
|
25
|
+
kind: string | null;
|
|
26
|
+
summary: string | null;
|
|
27
|
+
params: Array<{
|
|
28
|
+
name: string;
|
|
29
|
+
type: string | null;
|
|
30
|
+
description: string;
|
|
31
|
+
}>;
|
|
32
|
+
returns: string | null;
|
|
33
|
+
/** The declaration's place; `null` when no source declares it. */
|
|
34
|
+
place: SourcePlace | null;
|
|
35
|
+
}
|
|
36
|
+
/** @codexApi {"parent":"pithy.mcp.knowledge","name":"KnowledgeExample","stability":"experimental","signature":"interface KnowledgeExample { name: string; file: string; line: number; code: string }"} */
|
|
37
|
+
/** A test marked `// @codex:example <entry id>`. */
|
|
38
|
+
export interface KnowledgeExample {
|
|
39
|
+
name: string;
|
|
40
|
+
file: string;
|
|
41
|
+
line: number;
|
|
42
|
+
code: string;
|
|
43
|
+
}
|
|
44
|
+
/** @codexApi {"parent":"pithy.mcp.knowledge","name":"KnowledgeEntry","stability":"experimental","signature":"interface KnowledgeEntry"} */
|
|
45
|
+
/** A Codex entry with its APIs, places and examples. */
|
|
46
|
+
export interface KnowledgeEntry {
|
|
47
|
+
id: string;
|
|
48
|
+
title: string | null;
|
|
49
|
+
category: string | null;
|
|
50
|
+
tags: string[];
|
|
51
|
+
related: string[];
|
|
52
|
+
places: SourcePlace[];
|
|
53
|
+
apis: KnowledgeApi[];
|
|
54
|
+
examples: KnowledgeExample[];
|
|
55
|
+
}
|
|
56
|
+
/** @codexApi {"parent":"pithy.mcp.knowledge","name":"KnowledgeComponent","stability":"experimental","signature":"interface KnowledgeComponent { name: string; id: string; file: string; spec: Record<string, unknown> }"} */
|
|
57
|
+
/** A PIDL spec and the file it was read from. */
|
|
58
|
+
export interface KnowledgeComponent {
|
|
59
|
+
name: string;
|
|
60
|
+
id: string;
|
|
61
|
+
file: string;
|
|
62
|
+
spec: Record<string, unknown>;
|
|
63
|
+
}
|
|
64
|
+
/** @codexApi {"parent":"pithy.mcp.knowledge","name":"Knowledge","stability":"experimental","signature":"interface Knowledge"} */
|
|
65
|
+
/** Everything the tools answer from. Serialised as `dist/snapshot.json`. */
|
|
66
|
+
export interface Knowledge {
|
|
67
|
+
format: 1;
|
|
68
|
+
scope: KnowledgeScope;
|
|
69
|
+
entries: KnowledgeEntry[];
|
|
70
|
+
components: KnowledgeComponent[];
|
|
71
|
+
tokens: {
|
|
72
|
+
file: string;
|
|
73
|
+
names: string[];
|
|
74
|
+
};
|
|
75
|
+
}
|
|
76
|
+
/** @codexApi {"parent":"pithy.mcp.knowledge","name":"CodexDataLike","stability":"experimental","signature":"interface CodexDataLike"} */
|
|
77
|
+
/** The shape `readCodex` from `@pithyjs/codex/reader` returns. */
|
|
78
|
+
export interface CodexDataLike {
|
|
79
|
+
index: {
|
|
80
|
+
entries: Array<{
|
|
81
|
+
id: string;
|
|
82
|
+
title?: string;
|
|
83
|
+
category?: string;
|
|
84
|
+
tags?: string[];
|
|
85
|
+
related?: string[];
|
|
86
|
+
apis?: Array<{
|
|
87
|
+
name: string;
|
|
88
|
+
stability?: string;
|
|
89
|
+
signature?: string;
|
|
90
|
+
}>;
|
|
91
|
+
}>;
|
|
92
|
+
};
|
|
93
|
+
sources: {
|
|
94
|
+
entries: Record<string, SourcePlace[]>;
|
|
95
|
+
apis: Record<string, Array<SourcePlace & {
|
|
96
|
+
kind: string | null;
|
|
97
|
+
signature: string | null;
|
|
98
|
+
summary: string | null;
|
|
99
|
+
params: KnowledgeApi['params'];
|
|
100
|
+
returns: string | null;
|
|
101
|
+
}>>;
|
|
102
|
+
examples: Record<string, KnowledgeExample[]>;
|
|
103
|
+
};
|
|
104
|
+
}
|
|
105
|
+
/**
|
|
106
|
+
* Joins Codex data with PIDL specs and token names into {@link Knowledge}.
|
|
107
|
+
* Each index API takes the source declaration with its signature, else the
|
|
108
|
+
* first one, and serves that declaration's signature; examples are only those
|
|
109
|
+
* Codex read from tests.
|
|
110
|
+
*
|
|
111
|
+
* @param codex - `readCodex` output.
|
|
112
|
+
* @param scope - The scope `codex` was read at.
|
|
113
|
+
* @param components - PIDL specs.
|
|
114
|
+
* @param tokens - Token names and the file they came from.
|
|
115
|
+
* @returns The knowledge the tools read.
|
|
116
|
+
*/
|
|
117
|
+
/** @codexApi {"parent":"pithy.mcp.knowledge","name":"assembleKnowledge","stability":"experimental","signature":"(codex: CodexDataLike, scope: KnowledgeScope, components: KnowledgeComponent[], tokens: Knowledge['tokens']) => Knowledge"} */
|
|
118
|
+
export declare function assembleKnowledge(codex: CodexDataLike, scope: KnowledgeScope, components: KnowledgeComponent[], tokens: Knowledge['tokens']): Knowledge;
|
|
119
|
+
/**
|
|
120
|
+
* Builds {@link Knowledge} from a checkout: Codex data through
|
|
121
|
+
* `@pithyjs/codex/reader` (imported here, on demand), PIDL specs and token
|
|
122
|
+
* names read from disk. The build script calls it with `public` for the
|
|
123
|
+
* snapshot; repo mode calls it with `all`.
|
|
124
|
+
*
|
|
125
|
+
* @param root - The repository root, which holds `codex.index.json`.
|
|
126
|
+
* @param scope - Which packages to cover.
|
|
127
|
+
* @returns The knowledge for that scope.
|
|
128
|
+
* @throws When `@pithyjs/codex` is not installed or `codex.index.json` is missing.
|
|
129
|
+
*/
|
|
130
|
+
/** @codexApi {"parent":"pithy.mcp.knowledge","name":"buildKnowledge","stability":"experimental","signature":"(root: string, scope: KnowledgeScope) => Promise<Knowledge>"} */
|
|
131
|
+
export declare function buildKnowledge(root: string, scope: KnowledgeScope): Promise<Knowledge>;
|
|
132
|
+
/**
|
|
133
|
+
* Reads a serialised {@link Knowledge}; by default the snapshot bundled in
|
|
134
|
+
* this package's `dist/`.
|
|
135
|
+
*
|
|
136
|
+
* @param file - The snapshot file.
|
|
137
|
+
* @returns The knowledge it holds.
|
|
138
|
+
* @throws When the file is not a format-1 snapshot.
|
|
139
|
+
*/
|
|
140
|
+
/** @codexApi {"parent":"pithy.mcp.knowledge","name":"loadSnapshot","stability":"experimental","signature":"(file?: string | URL) => Knowledge"} */
|
|
141
|
+
export declare function loadSnapshot(file?: string | URL): Knowledge;
|
|
142
|
+
/**
|
|
143
|
+
* The nearest directory at or above `from` that holds `codex.index.json`.
|
|
144
|
+
*
|
|
145
|
+
* @param from - Where to start.
|
|
146
|
+
* @returns That directory, or `null` when there is none.
|
|
147
|
+
*/
|
|
148
|
+
/** @codexApi {"parent":"pithy.mcp.knowledge","name":"findRepoRoot","stability":"experimental","signature":"(from: string) => string | null"} */
|
|
149
|
+
export declare function findRepoRoot(from: string): string | null;
|
|
150
|
+
/**
|
|
151
|
+
* The citations of an entry: its `@codex` places, then its API declarations.
|
|
152
|
+
*
|
|
153
|
+
* @param entry - The entry.
|
|
154
|
+
* @returns One citation per place, or the index when Codex places it nowhere.
|
|
155
|
+
*/
|
|
156
|
+
/** @codexApi {"parent":"pithy.mcp.knowledge","name":"entryCitations","stability":"experimental","signature":"(entry: KnowledgeEntry) => Citation[]"} */
|
|
157
|
+
export declare function entryCitations(entry: KnowledgeEntry): Citation[];
|
|
@@ -0,0 +1,163 @@
|
|
|
1
|
+
/** @codex { "id": "pithy.mcp.knowledge", "title": "MCP Knowledge Model", "category": "feature", "risk": "medium" } */
|
|
2
|
+
import { existsSync, readdirSync, readFileSync } from 'node:fs';
|
|
3
|
+
import { dirname, join, relative, resolve, sep } from 'node:path';
|
|
4
|
+
const PIDL_DIR = 'packages/pidl-catalog/specs';
|
|
5
|
+
const TOKENS_FILE = 'packages/design-system/src/manifest/_generated/token-names.json';
|
|
6
|
+
// The reader lists in readdir order, which differs across file systems.
|
|
7
|
+
const byPlace = (list = []) => [...list].sort((a, b) => a.file < b.file ? -1 : a.file > b.file ? 1 : a.line - b.line);
|
|
8
|
+
const readJson = (path) => JSON.parse(readFileSync(path, 'utf8'));
|
|
9
|
+
/**
|
|
10
|
+
* Joins Codex data with PIDL specs and token names into {@link Knowledge}.
|
|
11
|
+
* Each index API takes the source declaration with its signature, else the
|
|
12
|
+
* first one, and serves that declaration's signature; examples are only those
|
|
13
|
+
* Codex read from tests.
|
|
14
|
+
*
|
|
15
|
+
* @param codex - `readCodex` output.
|
|
16
|
+
* @param scope - The scope `codex` was read at.
|
|
17
|
+
* @param components - PIDL specs.
|
|
18
|
+
* @param tokens - Token names and the file they came from.
|
|
19
|
+
* @returns The knowledge the tools read.
|
|
20
|
+
*/
|
|
21
|
+
/** @codexApi {"parent":"pithy.mcp.knowledge","name":"assembleKnowledge","stability":"experimental","signature":"(codex: CodexDataLike, scope: KnowledgeScope, components: KnowledgeComponent[], tokens: Knowledge['tokens']) => Knowledge"} */
|
|
22
|
+
export function assembleKnowledge(codex, scope, components, tokens) {
|
|
23
|
+
const entries = codex.index.entries.map((e) => {
|
|
24
|
+
const apis = (e.apis ?? []).map((a) => {
|
|
25
|
+
const decls = byPlace(codex.sources.apis[`${e.id} ${a.name}`]);
|
|
26
|
+
const decl = decls.find(d => d.signature === (a.signature ?? null)) ?? decls[0];
|
|
27
|
+
return {
|
|
28
|
+
name: a.name,
|
|
29
|
+
stability: a.stability ?? null,
|
|
30
|
+
// The source is current; the index can lag it.
|
|
31
|
+
signature: decl?.signature ?? a.signature ?? null,
|
|
32
|
+
kind: decl?.kind ?? null,
|
|
33
|
+
summary: decl?.summary ?? null,
|
|
34
|
+
params: decl?.params ?? [],
|
|
35
|
+
returns: decl?.returns ?? null,
|
|
36
|
+
place: decl
|
|
37
|
+
? { pkg: decl.pkg, file: decl.file, line: decl.line }
|
|
38
|
+
: null,
|
|
39
|
+
};
|
|
40
|
+
});
|
|
41
|
+
return {
|
|
42
|
+
id: e.id,
|
|
43
|
+
title: e.title ?? null,
|
|
44
|
+
category: e.category ?? null,
|
|
45
|
+
tags: e.tags ?? [],
|
|
46
|
+
related: e.related ?? [],
|
|
47
|
+
places: byPlace(codex.sources.entries[e.id]),
|
|
48
|
+
apis,
|
|
49
|
+
examples: byPlace(codex.sources.examples[e.id]),
|
|
50
|
+
};
|
|
51
|
+
});
|
|
52
|
+
return { format: 1, scope, entries, components, tokens };
|
|
53
|
+
}
|
|
54
|
+
function readComponents(root) {
|
|
55
|
+
const out = [];
|
|
56
|
+
const walk = (dir) => {
|
|
57
|
+
if (!existsSync(dir))
|
|
58
|
+
return;
|
|
59
|
+
const items = readdirSync(dir, { withFileTypes: true }).sort((a, b) => a.name < b.name ? -1 : 1);
|
|
60
|
+
for (const item of items) {
|
|
61
|
+
const path = join(dir, item.name);
|
|
62
|
+
if (item.isDirectory())
|
|
63
|
+
walk(path);
|
|
64
|
+
else if (item.name.endsWith('.pidl.json')) {
|
|
65
|
+
const spec = readJson(path);
|
|
66
|
+
out.push({
|
|
67
|
+
name: String(spec.name),
|
|
68
|
+
id: String(spec.id),
|
|
69
|
+
file: relative(root, path).split(sep).join('/'),
|
|
70
|
+
spec,
|
|
71
|
+
});
|
|
72
|
+
}
|
|
73
|
+
}
|
|
74
|
+
};
|
|
75
|
+
walk(join(root, PIDL_DIR));
|
|
76
|
+
return out;
|
|
77
|
+
}
|
|
78
|
+
/**
|
|
79
|
+
* Builds {@link Knowledge} from a checkout: Codex data through
|
|
80
|
+
* `@pithyjs/codex/reader` (imported here, on demand), PIDL specs and token
|
|
81
|
+
* names read from disk. The build script calls it with `public` for the
|
|
82
|
+
* snapshot; repo mode calls it with `all`.
|
|
83
|
+
*
|
|
84
|
+
* @param root - The repository root, which holds `codex.index.json`.
|
|
85
|
+
* @param scope - Which packages to cover.
|
|
86
|
+
* @returns The knowledge for that scope.
|
|
87
|
+
* @throws When `@pithyjs/codex` is not installed or `codex.index.json` is missing.
|
|
88
|
+
*/
|
|
89
|
+
/** @codexApi {"parent":"pithy.mcp.knowledge","name":"buildKnowledge","stability":"experimental","signature":"(root: string, scope: KnowledgeScope) => Promise<Knowledge>"} */
|
|
90
|
+
export async function buildKnowledge(root, scope) {
|
|
91
|
+
let reader;
|
|
92
|
+
try {
|
|
93
|
+
reader = (await import('@pithyjs/codex/reader'));
|
|
94
|
+
}
|
|
95
|
+
catch (e) {
|
|
96
|
+
throw new Error(`Repo mode needs @pithyjs/codex installed beside @pithyjs/mcp (${e.message})`);
|
|
97
|
+
}
|
|
98
|
+
const abs = resolve(root);
|
|
99
|
+
const tokens = readJson(join(abs, TOKENS_FILE)).tokens;
|
|
100
|
+
return assembleKnowledge(reader.readCodex({ root: abs, scope }), scope, readComponents(abs), { file: TOKENS_FILE, names: tokens });
|
|
101
|
+
}
|
|
102
|
+
/**
|
|
103
|
+
* Reads a serialised {@link Knowledge}; by default the snapshot bundled in
|
|
104
|
+
* this package's `dist/`.
|
|
105
|
+
*
|
|
106
|
+
* @param file - The snapshot file.
|
|
107
|
+
* @returns The knowledge it holds.
|
|
108
|
+
* @throws When the file is not a format-1 snapshot.
|
|
109
|
+
*/
|
|
110
|
+
/** @codexApi {"parent":"pithy.mcp.knowledge","name":"loadSnapshot","stability":"experimental","signature":"(file?: string | URL) => Knowledge"} */
|
|
111
|
+
export function loadSnapshot(file = new URL('./snapshot.json', import.meta.url)) {
|
|
112
|
+
const k = JSON.parse(readFileSync(file, 'utf8'));
|
|
113
|
+
if (k?.format !== 1 ||
|
|
114
|
+
!Array.isArray(k.entries) ||
|
|
115
|
+
!Array.isArray(k.components) ||
|
|
116
|
+
!Array.isArray(k.tokens?.names)) {
|
|
117
|
+
throw new Error(`${String(file)} is not a @pithyjs/mcp snapshot`);
|
|
118
|
+
}
|
|
119
|
+
return k;
|
|
120
|
+
}
|
|
121
|
+
/**
|
|
122
|
+
* The nearest directory at or above `from` that holds `codex.index.json`.
|
|
123
|
+
*
|
|
124
|
+
* @param from - Where to start.
|
|
125
|
+
* @returns That directory, or `null` when there is none.
|
|
126
|
+
*/
|
|
127
|
+
/** @codexApi {"parent":"pithy.mcp.knowledge","name":"findRepoRoot","stability":"experimental","signature":"(from: string) => string | null"} */
|
|
128
|
+
export function findRepoRoot(from) {
|
|
129
|
+
let dir = resolve(from);
|
|
130
|
+
for (;;) {
|
|
131
|
+
if (existsSync(join(dir, 'codex.index.json')))
|
|
132
|
+
return dir;
|
|
133
|
+
const up = dirname(dir);
|
|
134
|
+
if (up === dir)
|
|
135
|
+
return null;
|
|
136
|
+
dir = up;
|
|
137
|
+
}
|
|
138
|
+
}
|
|
139
|
+
/**
|
|
140
|
+
* The citations of an entry: its `@codex` places, then its API declarations.
|
|
141
|
+
*
|
|
142
|
+
* @param entry - The entry.
|
|
143
|
+
* @returns One citation per place, or the index when Codex places it nowhere.
|
|
144
|
+
*/
|
|
145
|
+
/** @codexApi {"parent":"pithy.mcp.knowledge","name":"entryCitations","stability":"experimental","signature":"(entry: KnowledgeEntry) => Citation[]"} */
|
|
146
|
+
export function entryCitations(entry) {
|
|
147
|
+
const out = [];
|
|
148
|
+
const seen = new Set();
|
|
149
|
+
const add = (p) => {
|
|
150
|
+
const key = `${p.file}:${p.line}`;
|
|
151
|
+
if (seen.has(key))
|
|
152
|
+
return;
|
|
153
|
+
seen.add(key);
|
|
154
|
+
out.push({ entryId: entry.id, file: p.file, line: p.line });
|
|
155
|
+
};
|
|
156
|
+
entry.places.forEach(add);
|
|
157
|
+
for (const a of entry.apis)
|
|
158
|
+
if (a.place)
|
|
159
|
+
add(a.place);
|
|
160
|
+
return out.length > 0
|
|
161
|
+
? out
|
|
162
|
+
: [{ entryId: entry.id, file: 'codex.index.json' }];
|
|
163
|
+
}
|
package/dist/lookup.d.ts
ADDED
|
@@ -0,0 +1,47 @@
|
|
|
1
|
+
/** @codex { "id": "pithy.mcp.lookup", "title": "MCP Grounded Lookup", "category": "feature", "risk": "medium" } */
|
|
2
|
+
import { type Citation, type Knowledge, type KnowledgeComponent, type KnowledgeEntry } from './knowledge.js';
|
|
3
|
+
import { type SearchHit } from './search.js';
|
|
4
|
+
/** @codexApi {"parent":"pithy.mcp.lookup","name":"NotFound","stability":"experimental","signature":"interface NotFound { found: false; query: string; message: string; suggestions: SearchHit[] }"} */
|
|
5
|
+
/** What a lookup returns instead of a guess. */
|
|
6
|
+
export interface NotFound {
|
|
7
|
+
found: false;
|
|
8
|
+
query: string;
|
|
9
|
+
message: string;
|
|
10
|
+
suggestions: SearchHit[];
|
|
11
|
+
}
|
|
12
|
+
/** @codexApi {"parent":"pithy.mcp.lookup","name":"ApiResult","stability":"experimental","signature":"type ApiResult = { found: true; query: string; entries: KnowledgeEntry[]; citations: Citation[] } | NotFound"} */
|
|
13
|
+
/** The entries an id or API name resolves to, with their citations. */
|
|
14
|
+
export type ApiResult = {
|
|
15
|
+
found: true;
|
|
16
|
+
query: string;
|
|
17
|
+
entries: KnowledgeEntry[];
|
|
18
|
+
citations: Citation[];
|
|
19
|
+
} | NotFound;
|
|
20
|
+
/** @codexApi {"parent":"pithy.mcp.lookup","name":"ComponentResult","stability":"experimental","signature":"type ComponentResult = { found: true; component: KnowledgeComponent; citations: Citation[] } | NotFound"} */
|
|
21
|
+
/** A PIDL spec and its citation. */
|
|
22
|
+
export type ComponentResult = {
|
|
23
|
+
found: true;
|
|
24
|
+
component: KnowledgeComponent;
|
|
25
|
+
citations: Citation[];
|
|
26
|
+
} | NotFound;
|
|
27
|
+
/**
|
|
28
|
+
* Resolves an entry id, or else an API name, to Codex entries. An API name
|
|
29
|
+
* returns each entry that declares it, cut to that API. Examples are the
|
|
30
|
+
* entry's `@codex:example` tests, unchanged.
|
|
31
|
+
*
|
|
32
|
+
* @param k - The knowledge to read.
|
|
33
|
+
* @param query - An entry id such as `pithy.mcp.server`, or an API name.
|
|
34
|
+
* @returns The entries and their citations, or {@link NotFound}.
|
|
35
|
+
*/
|
|
36
|
+
/** @codexApi {"parent":"pithy.mcp.lookup","name":"getApi","stability":"experimental","signature":"(k: Knowledge, query: string) => ApiResult"} */
|
|
37
|
+
export declare function getApi(k: Knowledge, query: string): ApiResult;
|
|
38
|
+
/**
|
|
39
|
+
* Finds a component's PIDL spec by name (`Button`), kebab name (`page-section`),
|
|
40
|
+
* id (`ui.button`) or display name, ignoring case.
|
|
41
|
+
*
|
|
42
|
+
* @param k - The knowledge to read.
|
|
43
|
+
* @param name - The component to find.
|
|
44
|
+
* @returns The spec and its file, or {@link NotFound}.
|
|
45
|
+
*/
|
|
46
|
+
/** @codexApi {"parent":"pithy.mcp.lookup","name":"getComponent","stability":"experimental","signature":"(k: Knowledge, name: string) => ComponentResult"} */
|
|
47
|
+
export declare function getComponent(k: Knowledge, name: string): ComponentResult;
|
package/dist/lookup.js
ADDED
|
@@ -0,0 +1,69 @@
|
|
|
1
|
+
/** @codex { "id": "pithy.mcp.lookup", "title": "MCP Grounded Lookup", "category": "feature", "risk": "medium" } */
|
|
2
|
+
import { entryCitations, } from './knowledge.js';
|
|
3
|
+
import { search } from './search.js';
|
|
4
|
+
const notFound = (k, query, what, kind) => ({
|
|
5
|
+
found: false,
|
|
6
|
+
query,
|
|
7
|
+
message: `No ${what} matches "${query}" in the ${k.scope === 'public' ? 'published packages' : 'checkout'}.`,
|
|
8
|
+
suggestions: search(k, query, 20)
|
|
9
|
+
.filter(h => !kind || h.kind === kind)
|
|
10
|
+
.slice(0, 5),
|
|
11
|
+
});
|
|
12
|
+
/**
|
|
13
|
+
* Resolves an entry id, or else an API name, to Codex entries. An API name
|
|
14
|
+
* returns each entry that declares it, cut to that API. Examples are the
|
|
15
|
+
* entry's `@codex:example` tests, unchanged.
|
|
16
|
+
*
|
|
17
|
+
* @param k - The knowledge to read.
|
|
18
|
+
* @param query - An entry id such as `pithy.mcp.server`, or an API name.
|
|
19
|
+
* @returns The entries and their citations, or {@link NotFound}.
|
|
20
|
+
*/
|
|
21
|
+
/** @codexApi {"parent":"pithy.mcp.lookup","name":"getApi","stability":"experimental","signature":"(k: Knowledge, query: string) => ApiResult"} */
|
|
22
|
+
export function getApi(k, query) {
|
|
23
|
+
const q = query.trim();
|
|
24
|
+
const byId = k.entries.find(e => e.id === q);
|
|
25
|
+
let entries = byId ? [byId] : [];
|
|
26
|
+
if (!byId) {
|
|
27
|
+
for (const exact of [true, false]) {
|
|
28
|
+
const same = (n) => exact ? n === q : n.toLowerCase() === q.toLowerCase();
|
|
29
|
+
entries = k.entries
|
|
30
|
+
.filter(e => e.apis.some(a => same(a.name)))
|
|
31
|
+
.map(e => ({ ...e, apis: e.apis.filter(a => same(a.name)) }));
|
|
32
|
+
if (entries.length > 0)
|
|
33
|
+
break;
|
|
34
|
+
}
|
|
35
|
+
}
|
|
36
|
+
if (entries.length === 0)
|
|
37
|
+
return notFound(k, q, 'entry or API');
|
|
38
|
+
return {
|
|
39
|
+
found: true,
|
|
40
|
+
query: q,
|
|
41
|
+
entries,
|
|
42
|
+
citations: entries.flatMap(entryCitations),
|
|
43
|
+
};
|
|
44
|
+
}
|
|
45
|
+
// `CTASection` → `cta-section`.
|
|
46
|
+
const kebab = (name) => name
|
|
47
|
+
.replace(/([a-z0-9])([A-Z])/g, '$1-$2')
|
|
48
|
+
.replace(/([A-Z]+)([A-Z][a-z])/g, '$1-$2')
|
|
49
|
+
.toLowerCase();
|
|
50
|
+
/**
|
|
51
|
+
* Finds a component's PIDL spec by name (`Button`), kebab name (`page-section`),
|
|
52
|
+
* id (`ui.button`) or display name, ignoring case.
|
|
53
|
+
*
|
|
54
|
+
* @param k - The knowledge to read.
|
|
55
|
+
* @param name - The component to find.
|
|
56
|
+
* @returns The spec and its file, or {@link NotFound}.
|
|
57
|
+
*/
|
|
58
|
+
/** @codexApi {"parent":"pithy.mcp.lookup","name":"getComponent","stability":"experimental","signature":"(k: Knowledge, name: string) => ComponentResult"} */
|
|
59
|
+
export function getComponent(k, name) {
|
|
60
|
+
const q = name.trim().toLowerCase();
|
|
61
|
+
const component = k.components.find(c => c.name.toLowerCase() === q ||
|
|
62
|
+
c.id.toLowerCase() === q ||
|
|
63
|
+
c.id.toLowerCase() === `ui.${q}` ||
|
|
64
|
+
kebab(c.name) === q ||
|
|
65
|
+
String(c.spec.displayName ?? '').toLowerCase() === q);
|
|
66
|
+
if (!component)
|
|
67
|
+
return notFound(k, name.trim(), 'component', 'component');
|
|
68
|
+
return { found: true, component, citations: [{ file: component.file }] };
|
|
69
|
+
}
|
package/dist/pidl.d.ts
ADDED
|
@@ -0,0 +1,27 @@
|
|
|
1
|
+
/** @codex { "id": "pithy.mcp.pidl", "title": "MCP PIDL Validator", "category": "feature", "risk": "medium" } */
|
|
2
|
+
import type { Citation } from './knowledge.js';
|
|
3
|
+
/** @codexApi {"parent":"pithy.mcp.pidl","name":"PidlIssue","stability":"experimental","signature":"interface PidlIssue { path: string; message: string }"} */
|
|
4
|
+
/** A problem at a JSON path such as `props[2].enum`; `''` is the whole spec. */
|
|
5
|
+
export interface PidlIssue {
|
|
6
|
+
path: string;
|
|
7
|
+
message: string;
|
|
8
|
+
}
|
|
9
|
+
/** @codexApi {"parent":"pithy.mcp.pidl","name":"PidlResult","stability":"experimental","signature":"interface PidlResult { valid: boolean; errors: PidlIssue[]; warnings: PidlIssue[]; citations: Citation[] }"} */
|
|
10
|
+
/** `valid` when there are no errors; warnings do not fail a spec. */
|
|
11
|
+
export interface PidlResult {
|
|
12
|
+
valid: boolean;
|
|
13
|
+
errors: PidlIssue[];
|
|
14
|
+
warnings: PidlIssue[];
|
|
15
|
+
citations: Citation[];
|
|
16
|
+
}
|
|
17
|
+
/**
|
|
18
|
+
* Validates a PIDL component spec against the format in
|
|
19
|
+
* `docs/site-builder/features/pidl.md`, the conventions every spec in
|
|
20
|
+
* `@pithyjs/pidl-catalog` follows, and then the registry's own
|
|
21
|
+
* `extractPublic`, so a valid spec is one the registry accepts.
|
|
22
|
+
*
|
|
23
|
+
* @param input - The spec, as an object or as JSON text.
|
|
24
|
+
* @returns Errors and warnings by JSON path.
|
|
25
|
+
*/
|
|
26
|
+
/** @codexApi {"parent":"pithy.mcp.pidl","name":"validatePidl","stability":"experimental","signature":"(input: unknown) => PidlResult"} */
|
|
27
|
+
export declare function validatePidl(input: unknown): PidlResult;
|