@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 +102 -2
- package/dist/snapshot.json +1 -1
- package/package.json +2 -2
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
|