@pithyjs/mcp 0.1.0-beta.1 → 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/README.md CHANGED
@@ -7,7 +7,6 @@ Every lookup answer carries `citations` (`{ entryId?, file, line? }`) taken from
7
7
  ## Installation
8
8
 
9
9
  <!-- @codex:auto install="@pithyjs/mcp" -->
10
-
11
10
  ```bash
12
11
  npm install @pithyjs/mcp
13
12
  ```
@@ -19,7 +18,6 @@ pnpm add @pithyjs/mcp
19
18
  ```bash
20
19
  yarn add @pithyjs/mcp
21
20
  ```
22
-
23
21
  <!-- @codex:end -->
24
22
 
25
23
  You do not need to install it to use it: `npx @pithyjs/mcp` runs the server.
@@ -106,16 +104,118 @@ Importing the package starts nothing. `buildKnowledge(root, 'public' | 'all')` b
106
104
  ## API
107
105
 
108
106
  <!-- @codex:auto api="pithy.mcp.*" -->
107
+ | API | Component | Signature | Stability | Description |
108
+ | --- | --- | --- | --- | --- |
109
+ | GuardLimits | guard | `interface GuardLimits { maxDepth: number; maxValues: number; maxChars: number }` | experimental | The bounds {@link guardInput} enforces. |
110
+ | GuardError | guard | `class GuardError extends Error` | experimental | Thrown by {@link guardInput}; the message names the offending path. |
111
+ | guardInput | guard | `(value: unknown, limits?: GuardLimits) => void` | experimental | - |
112
+ | guardTransport | guard | `(inner: Transport) => Transport` | experimental | - |
113
+ | KnowledgeScope | knowledge | `type KnowledgeScope = 'public' | 'all'` | experimental | `public`: published packages only. `all`: every package in the checkout. |
114
+ | Citation | knowledge | `interface Citation { entryId?: string; file: string; line?: number }` | experimental | Where an answer comes from: a repo-relative file, and the line when known. |
115
+ | SourcePlace | knowledge | `interface SourcePlace { pkg: string; file: string; line: number }` | experimental | An annotation's package, repo-relative file and line. |
116
+ | KnowledgeApi | knowledge | `interface KnowledgeApi` | experimental | One `@codexApi`, joined with the declaration it annotates. |
117
+ | KnowledgeExample | knowledge | `interface KnowledgeExample { name: string; file: string; line: number; code: string }` | experimental | A test marked `// @codex:example <entry id>`. |
118
+ | KnowledgeEntry | knowledge | `interface KnowledgeEntry` | experimental | A Codex entry with its APIs, places and examples. |
119
+ | KnowledgeComponent | knowledge | `interface KnowledgeComponent { name: string; id: string; file: string; spec: Record<string, unknown> }` | experimental | A PIDL spec and the file it was read from. |
120
+ | Knowledge | knowledge | `interface Knowledge` | experimental | Everything the tools answer from. Serialised as `dist/snapshot.json`. |
121
+ | CodexDataLike | knowledge | `interface CodexDataLike` | experimental | The shape `readCodex` from `@pithyjs/codex/reader` returns. |
122
+ | assembleKnowledge | knowledge | `(codex: CodexDataLike, scope: KnowledgeScope, components: KnowledgeComponent[], tokens: Knowledge['tokens']) => Knowledge` | experimental | - |
123
+ | buildKnowledge | knowledge | `(root: string, scope: KnowledgeScope) => Promise<Knowledge>` | experimental | - |
124
+ | loadSnapshot | knowledge | `(file?: string | URL) => Knowledge` | experimental | - |
125
+ | findRepoRoot | knowledge | `(from: string) => string | null` | experimental | - |
126
+ | entryCitations | knowledge | `(entry: KnowledgeEntry) => Citation[]` | experimental | - |
127
+ | NotFound | lookup | `interface NotFound { found: false; query: string; message: string; suggestions: SearchHit[] }` | experimental | What a lookup returns instead of a guess. |
128
+ | ApiResult | lookup | `type ApiResult = { found: true; query: string; entries: KnowledgeEntry[]; citations: Citation[] } | NotFound` | experimental | The entries an id or API name resolves to, with their citations. |
129
+ | ComponentResult | lookup | `type ComponentResult = { found: true; component: KnowledgeComponent; citations: Citation[] } | NotFound` | experimental | A PIDL spec and its citation. |
130
+ | getApi | lookup | `(k: Knowledge, query: string) => ApiResult` | experimental | - |
131
+ | getComponent | lookup | `(k: Knowledge, name: string) => ComponentResult` | experimental | - |
132
+ | PidlIssue | pidl | `interface PidlIssue { path: string; message: string }` | experimental | A problem at a JSON path such as `props[2].enum`; `''` is the whole spec. |
133
+ | PidlResult | pidl | `interface PidlResult { valid: boolean; errors: PidlIssue[]; warnings: PidlIssue[]; citations: Citation[] }` | experimental | `valid` when there are no errors; warnings do not fail a spec. |
134
+ | validatePidl | pidl | `(input: unknown) => PidlResult` | experimental | - |
135
+ | ScaffoldFile | scaffold | `interface ScaffoldFile { path: string; contents: string }` | experimental | A file to create, at a path relative to the app root. |
136
+ | Scaffold | scaffold | `interface Scaffold { files: ScaffoldFile[] }` | experimental | Files for the caller to write; nothing is written here. |
137
+ | ComponentKind | scaffold | `type ComponentKind = 'atom' | 'molecule' | 'organism' | 'section'` | experimental | The PIDL level of a scaffolded component. |
138
+ | scaffoldRoute | scaffold | `(path: string, options?: { loader?: boolean; layout?: boolean }) => Scaffold` | experimental | - |
139
+ | takenComponentNames | scaffold | `(k: Knowledge) => string[]` | experimental | - |
140
+ | scaffoldComponent | scaffold | `(name: string, kind?: ComponentKind, existing?: readonly string[]) => Scaffold` | experimental | - |
141
+ | SearchHit | search | `interface SearchHit` | experimental | One ranked result. `id` is an entry id, `"<entry id> <api>"`, or a component name. |
142
+ | MAX_SEARCH_LIMIT | search | `50` | experimental | The most hits one search returns. |
143
+ | tokenize | search | `(text: string) => string[]` | experimental | - |
144
+ | search | search | `(k: Knowledge, query: string, limit?: number) => SearchHit[]` | experimental | - |
145
+ | TOOL_NAMES | server | `readonly string[]` | experimental | Every tool the server registers. |
146
+ | createPithyServer | server | `(knowledge: Knowledge) => McpServer` | experimental | - |
147
+ | connectPithyServer | server | `(server: McpServer, transport: Transport) => Promise<void>` | experimental | - |
148
+ | TemplateCheck | template | `interface TemplateCheck { filename: string; checked: boolean; ok: boolean; findings: TemplateFinding[]; error?: string; note?: string }` | experimental | `checked` is false when the file type is one the plugin never reads. `ok` is true only for a checked module with no findings and no error. |
149
+ | checkTemplate | template | `(code: string, filename?: string) => Promise<TemplateCheck>` | experimental | - |
150
+ | suggestToken | tokens | `(token: string, known: ReadonlySet<string>) => string | null` | experimental | - |
151
+ | TokenIssue | tokens | `interface TokenIssue` | experimental | One problem `check_tokens` found. |
152
+ | TokenCheck | tokens | `interface TokenCheck { ok: boolean; issues: TokenIssue[]; total: number; truncated: boolean }` | experimental | `ok` when there are no issues; `issues` lists the first 200 of `total`. |
153
+ | checkTokens | tokens | `(css: string, names: readonly string[]) => TokenCheck` | experimental | - |
154
+ | TokensResult | tokens | `type TokensResult` | experimental | Token names with their citation, or the families when `category` is unknown. |
155
+ | getTokens | tokens | `(k: Knowledge, category?: string) => TokensResult` | experimental | - |
156
+ | CatalogEntry | errors | `interface CatalogEntry` | experimental | A framework message, where it is emitted, and what it means. |
157
+ | ERROR_CATALOG | errors | `readonly CatalogEntry[]` | experimental | Framework messages `explain_error` knows, each citing the file that emits it. |
158
+ | ExplainResult | errors | `type ExplainResult` | experimental | A catalog explanation with its citation, or a plain "not known". |
159
+ | explainError | errors | `(k: Knowledge, message: string) => ExplainResult` | experimental | - |
109
160
  <!-- @codex:end -->
110
161
 
111
162
  ## Examples
112
163
 
113
164
  <!-- @codex:auto examples="pithy.mcp.*" limit="3" -->
165
+ **initializes over stdio and lists tools from the bundled snapshot**
166
+
167
+ ```typescript
168
+ const [tools, privateEntry] = await withClient(
169
+ [],
170
+ async c =>
171
+ [
172
+ (await c.listTools()).tools,
173
+ JSON.parse(
174
+ (
175
+ (await c.callTool({
176
+ name: 'get_api',
177
+ arguments: { query: 'pithy.server.middleware' },
178
+ })) as {
179
+ content: Array<{ text: string }>;
180
+ }
181
+ ).content[0].text
182
+ ),
183
+ ] as const
184
+ );
185
+ tools.map(t => t.name); // contains 'get_api'
186
+ tools; // has length 10
187
+ privateEntry.found; // → false
188
+ ```
189
+
190
+ **rejects an own \_\_proto\_\_ key, as JSON.parse creates one**
191
+
192
+ ```typescript
193
+ const value = JSON.parse('{"__proto__":{"x":1}}');
194
+ Object.getOwnPropertyNames(value); // → ['__proto__']
195
+ rejects(value, /__proto__/);
196
+ expect(() => guardInput(value)).toThrow(GuardError);
197
+ ```
198
+
199
+ **builds public knowledge from published packages only**
200
+
201
+ ```typescript
202
+ const k = await repoKnowledge('public');
203
+ k.format; // → 1
204
+ k.scope; // → 'public'
205
+ const places = placesOf(k);
206
+ expect(places.length).toBeGreaterThan(100);
207
+ places.filter(p => isPrivate(p.file)); // → []
208
+ ```
114
209
  <!-- @codex:end -->
115
210
 
116
211
  ## Testing
117
212
 
118
213
  <!-- @codex:auto testing="pithy.mcp.server" -->
214
+ | Feature | Unit | Integration | E2E | Status |
215
+ | --- | --- | --- | --- | --- |
216
+ | TOOL_NAMES | ✓ | - | - | Missing integration |
217
+ | createPithyServer | ✓ | - | - | Missing integration |
218
+ | connectPithyServer | ✓ | - | - | Missing integration |
119
219
  <!-- @codex:end -->
120
220
 
121
221
  ```bash