@3ngram/server 1.2.7 → 1.4.1
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/dist/mcp/completions.d.ts +13 -0
- package/dist/mcp/completions.js +67 -0
- package/dist/mcp/completions.js.map +1 -0
- package/dist/mcp/prompts.d.ts +4 -3
- package/dist/mcp/prompts.js +34 -16
- package/dist/mcp/prompts.js.map +1 -1
- package/dist/mcp/resources.d.ts +43 -0
- package/dist/mcp/resources.js +156 -0
- package/dist/mcp/resources.js.map +1 -0
- package/dist/mcp/server.d.ts +21 -4
- package/dist/mcp/server.js +58 -5
- package/dist/mcp/server.js.map +1 -1
- package/dist/mcp/tool-annotations.d.ts +11 -0
- package/dist/mcp/tool-annotations.js +15 -0
- package/dist/mcp/tool-annotations.js.map +1 -0
- package/dist/mcp/tools-admin.js +91 -18
- package/dist/mcp/tools-admin.js.map +1 -1
- package/dist/mcp/tools-inspect.js +8 -1
- package/dist/mcp/tools-inspect.js.map +1 -1
- package/dist/mcp/tools-orient.js +9 -1
- package/dist/mcp/tools-orient.js.map +1 -1
- package/dist/mcp/tools-search.js +192 -84
- package/dist/mcp/tools-search.js.map +1 -1
- package/dist/mcp/tools.d.ts +27 -2
- package/dist/mcp/tools.js +104 -14
- package/dist/mcp/tools.js.map +1 -1
- package/dist/middleware/mcp-header-observability.js +23 -0
- package/dist/middleware/mcp-header-observability.js.map +1 -1
- package/dist/middleware/mcp-origin.d.ts +14 -0
- package/dist/middleware/mcp-origin.js +65 -0
- package/dist/middleware/mcp-origin.js.map +1 -0
- package/dist/rest/route-helpers.d.ts +6 -1
- package/dist/rest/route-helpers.js +9 -0
- package/dist/rest/route-helpers.js.map +1 -1
- package/dist/rest/router.js +64 -13
- package/dist/rest/router.js.map +1 -1
- package/dist/rest/search-router.js +22 -8
- package/dist/rest/search-router.js.map +1 -1
- package/dist/routes/mcp.js +15 -0
- package/dist/routes/mcp.js.map +1 -1
- package/package.json +5 -5
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"tools-search.js","sourceRoot":"","sources":["../../src/mcp/tools-search.ts"],"names":[],"mappings":"AAAA,sCAAsC;AACtC,8EAA8E;AAC9E,4EAA4E;AAC5E,+EAA+E;AAC/E,uCAAuC;AACvC,EAAE;AACF,yEAAyE;AACzE,+EAA+E;AAC/E,oEAAoE;AACpE,mEAAmE;AACnE,OAAO,
|
|
1
|
+
{"version":3,"file":"tools-search.js","sourceRoot":"","sources":["../../src/mcp/tools-search.ts"],"names":[],"mappings":"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"}
|
package/dist/mcp/tools.d.ts
CHANGED
|
@@ -1,7 +1,7 @@
|
|
|
1
1
|
import { type AccessGate, type BudgetEnforcement, type LimitsResolver, type RetrievalPolicy } from '@3ngram/core';
|
|
2
2
|
import { type MemoryScope } from '@3ngram/core/auth';
|
|
3
3
|
import type { Gateway } from '@3ngram/llm';
|
|
4
|
-
import type { CallToolResult } from '@modelcontextprotocol/server';
|
|
4
|
+
import type { CallToolResult, ToolAnnotations } from '@modelcontextprotocol/server';
|
|
5
5
|
import type { ZodType } from 'zod';
|
|
6
6
|
/** The SDK result a tool returns: a text content mirror plus structured output. */
|
|
7
7
|
type ToolResult = CallToolResult;
|
|
@@ -36,6 +36,22 @@ export interface ToolDefinition {
|
|
|
36
36
|
description: string;
|
|
37
37
|
inputSchema: ZodType;
|
|
38
38
|
outputSchema: ZodType;
|
|
39
|
+
/**
|
|
40
|
+
* Behavioural hints a client uses to decide whether a call can be
|
|
41
|
+
* auto-approved or needs a confirmation prompt. REQUIRED on every tool (the
|
|
42
|
+
* registry invariant test enforces it): without them every tool looks
|
|
43
|
+
* equally dangerous, so a read like `search` collects the same friction as
|
|
44
|
+
* a write like `revise`.
|
|
45
|
+
*
|
|
46
|
+
* Deliberately NOT derived from {@link RequiredScope}. The mapping is not
|
|
47
|
+
* total — the per-action tools carry `anyOf` and span read AND write — and
|
|
48
|
+
* an explicit table is easier to review than a clever inference.
|
|
49
|
+
*
|
|
50
|
+
* `title` is available on ToolAnnotations too and is deliberately left
|
|
51
|
+
* unset: {@link ToolDefinition.config.title} already carries it, and two
|
|
52
|
+
* sources for one display string is how they drift.
|
|
53
|
+
*/
|
|
54
|
+
annotations: ToolAnnotations;
|
|
39
55
|
};
|
|
40
56
|
handler: (args: unknown, ctx: ToolContext) => Promise<ToolResult>;
|
|
41
57
|
}
|
|
@@ -81,7 +97,16 @@ export interface ToolContext {
|
|
|
81
97
|
* time, long after this assignment completes.
|
|
82
98
|
*/
|
|
83
99
|
export declare const TOOLS: readonly ToolDefinition[];
|
|
84
|
-
/**
|
|
100
|
+
/**
|
|
101
|
+
* Working ceiling per docs/concepts/mcp-design.mdx / hard rule 8. LEDGER: 11/12
|
|
102
|
+
* registered, and the twelfth is UNRESERVED — it goes to whichever tool next
|
|
103
|
+
* earns it on the JTBD + evidence test.
|
|
104
|
+
*
|
|
105
|
+
* The number is 3ngram's own, not the protocol's: the 2026-07-28 specification
|
|
106
|
+
* defines no maximum tool count and paginates `tools/list`. What it proxies for
|
|
107
|
+
* is description overlap and model selection accuracy, which is what to argue
|
|
108
|
+
* about when this binds. See docs/concepts/mcp-surface.mdx.
|
|
109
|
+
*/
|
|
85
110
|
export declare const MAX_TOOLS = 12;
|
|
86
111
|
/**
|
|
87
112
|
* Run a tool handler with uniform metrics + typed-error mapping. A KNOWN typed
|
package/dist/mcp/tools.js
CHANGED
|
@@ -17,9 +17,10 @@
|
|
|
17
17
|
import { log, mcpToolCalls, mcpToolErrors } from '@3ngram/config';
|
|
18
18
|
import { getFacts, remember, resolveByMemoryId, revise, } from '@3ngram/core';
|
|
19
19
|
import { MEMORY_READ_SCOPE, MEMORY_WRITE_SCOPE } from '@3ngram/core/auth';
|
|
20
|
-
import {
|
|
20
|
+
import { factsQueryInputV2Schema, factsToolOutputSchema, MAX_CONTENT_LENGTH, rememberToolInputV2Schema, rememberToolOutputV2Schema, resolveToolInputSchema, resolveToolOutputSchema, reviseToolInputSchema, reviseToolOutputSchema, } from '@3ngram/schema';
|
|
21
21
|
import { parseOutput } from '../output-validation.js';
|
|
22
22
|
import { mapToolError } from './errors.js';
|
|
23
|
+
import { READ_ONLY_ANNOTATIONS } from './tool-annotations.js';
|
|
23
24
|
// Admin tools: configure_scope / describe_environment /
|
|
24
25
|
// review_proposals — defined in their own module (500-line discipline), appended
|
|
25
26
|
// to the registry below via the factory (append-only edit to TOOLS).
|
|
@@ -29,7 +30,34 @@ import { INSPECT_TOOLS } from './tools-inspect.js';
|
|
|
29
30
|
import { ORIENT_TOOLS } from './tools-orient.js';
|
|
30
31
|
// --- search tool: fused retrieval — spliced in at its original position ---
|
|
31
32
|
import { SEARCH_TOOLS } from './tools-search.js';
|
|
32
|
-
/**
|
|
33
|
+
/**
|
|
34
|
+
* Wrap a structured payload as a tool success result: a JSON text mirror
|
|
35
|
+
* ALONGSIDE structuredContent. THE canonical explanation of that duplication —
|
|
36
|
+
* the identical helpers in tools-search / tools-orient / tools-inspect /
|
|
37
|
+
* tools-admin point here rather than restating it.
|
|
38
|
+
*
|
|
39
|
+
* WHY THE MIRROR STAYS (issue #75). `structuredContent` arrived in protocol
|
|
40
|
+
* revision 2025-06-18, but the SDK still serves 2025-03-26, 2024-11-05, and
|
|
41
|
+
* 2024-10-07 — and 2025-03-26 is what a client that sends no version negotiates
|
|
42
|
+
* by DEFAULT. Those revisions have no structuredContent at all, so their clients
|
|
43
|
+
* read `content` only. The SDK does not paper over this: a contentless result is
|
|
44
|
+
* normalized to `content: []`, so dropping the mirror would hand them an empty
|
|
45
|
+
* SUCCESS — a silent wrong answer, the worst failure mode available. Gating on
|
|
46
|
+
* the protocol ERA is not sufficient either, because the legacy era spans both
|
|
47
|
+
* sides of 2025-06-18; it would need per-VERSION gating.
|
|
48
|
+
*
|
|
49
|
+
* WHAT IT COSTS: slightly MORE than 2x, not exactly 2x. The mirror is
|
|
50
|
+
* stringified and then placed in a `text` field, so the envelope's own
|
|
51
|
+
* serialization escapes every quote and newline inside it a second time.
|
|
52
|
+
* Measured through this helper on a worst-case get_memories payload (the only
|
|
53
|
+
* tool whose budget makes this material): 284 KB structured + 315 KB mirror =
|
|
54
|
+
* 599 KB on the wire, a factor of 2.11x, of which the re-escaping is +10.7%.
|
|
55
|
+
* The cost is bounded and caller-requested — a caller asking for 20 full bodies
|
|
56
|
+
* asked for the bytes.
|
|
57
|
+
*
|
|
58
|
+
* test/mcp-text-mirror.test.ts pins the worst case under a named ceiling, so
|
|
59
|
+
* raising a get_memories budget cannot quietly double the wire cost with it.
|
|
60
|
+
*/
|
|
33
61
|
function ok(structured) {
|
|
34
62
|
return {
|
|
35
63
|
content: [{ type: 'text', text: JSON.stringify(structured) }],
|
|
@@ -53,6 +81,12 @@ function toAsOf(asOf) {
|
|
|
53
81
|
return undefined;
|
|
54
82
|
return defined({ validAt: toDate(asOf.validAt), asKnownAt: toDate(asOf.asKnownAt) });
|
|
55
83
|
}
|
|
84
|
+
/** Coerce a range's optional ISO-8601 bounds to Dates for the bi-temporal core query (range read). */
|
|
85
|
+
function toRange(range) {
|
|
86
|
+
if (range === undefined)
|
|
87
|
+
return undefined;
|
|
88
|
+
return defined({ from: toDate(range.from), to: toDate(range.to) });
|
|
89
|
+
}
|
|
56
90
|
/**
|
|
57
91
|
* remember — append a memory (docs/concepts/mcp-design.mdx JTBD "persist something worth
|
|
58
92
|
* keeping"). Validates via the canonical write schema, calls core remember()
|
|
@@ -68,16 +102,25 @@ const rememberTool = {
|
|
|
68
102
|
requiredScope: MEMORY_WRITE_SCOPE,
|
|
69
103
|
config: {
|
|
70
104
|
title: 'Remember',
|
|
71
|
-
description: `Append a new memory (decision, fact, preference, blocker, commitment, ...). Never merges; append-only. Content is capped at ${MAX_CONTENT_LENGTH} characters. To surface a commitment or blocker in a PROJECT-scoped briefing, pass \`project\` — a memory written with a NULL project never matches the bare project selector; only the scope_project selector's includeUnscoped: true opts it back in.`,
|
|
72
|
-
inputSchema:
|
|
73
|
-
outputSchema:
|
|
105
|
+
description: `Append a new memory (decision, fact, preference, blocker, commitment, ...). Never merges; append-only. Content is capped at ${MAX_CONTENT_LENGTH} characters. To surface a commitment or blocker in a PROJECT-scoped briefing, pass \`project\` — a memory written with a NULL project never matches the bare project selector; only the scope_project selector's includeUnscoped: true opts it back in. Optionally pass \`facts\`: the measurable claims the memory states, as subject/predicate/value triples that \`get_facts\` can then read back directly instead of re-reading the prose. Values are text, so put the unit in the predicate and keep one measure per fact (subject \`lift.back_squat\`, predicate \`top_set.weight_kg\`, value \`98\`). Give a fact a \`validFrom\` when it became true, if that is not now.`,
|
|
106
|
+
inputSchema: rememberToolInputV2Schema,
|
|
107
|
+
outputSchema: rememberToolOutputV2Schema,
|
|
108
|
+
// Appends a NEW row on every call, so repeating it is not a no-op —
|
|
109
|
+
// idempotentHint: false. destructiveHint: false is a real product claim:
|
|
110
|
+
// remember never merges into or overwrites an existing memory (hard rule 1).
|
|
111
|
+
annotations: {
|
|
112
|
+
readOnlyHint: false,
|
|
113
|
+
destructiveHint: false,
|
|
114
|
+
idempotentHint: false,
|
|
115
|
+
openWorldHint: false,
|
|
116
|
+
},
|
|
74
117
|
},
|
|
75
118
|
async handler(args, ctx) {
|
|
76
119
|
// core remember() is THE validation boundary; pass the args straight through.
|
|
77
120
|
// It returns the new id only, so the structured output echoes the NORMALIZED
|
|
78
121
|
// write input (scope default + null project applied here) for the rest.
|
|
79
122
|
// Embedding is on iff a gateway is configured — best-effort, never blocks.
|
|
80
|
-
const input =
|
|
123
|
+
const input = rememberToolInputV2Schema.parse(args);
|
|
81
124
|
const gatewayOpts = ctx.gateway === undefined
|
|
82
125
|
? { access: ctx.access, limits: ctx.limits }
|
|
83
126
|
: { gateway: ctx.gateway, budget: ctx.budget, access: ctx.access, limits: ctx.limits };
|
|
@@ -95,7 +138,7 @@ const rememberTool = {
|
|
|
95
138
|
// A commitment-type memory auto-creates an 'open' commitment in the same
|
|
96
139
|
// write tx; surface its id so the caller can `resolve`
|
|
97
140
|
// it without a follow-up lookup. Undefined (omitted) for every other type.
|
|
98
|
-
const output = parseOutput('remember',
|
|
141
|
+
const output = parseOutput('remember', rememberToolOutputV2Schema, defined({
|
|
99
142
|
memory: {
|
|
100
143
|
id: written.id,
|
|
101
144
|
memoryType: input.memoryType,
|
|
@@ -105,27 +148,39 @@ const rememberTool = {
|
|
|
105
148
|
},
|
|
106
149
|
embedded,
|
|
107
150
|
commitmentId: written.commitmentId,
|
|
151
|
+
// Ids only, and only when facts were written: `defined()` drops the key
|
|
152
|
+
// when undefined, so a write without facts returns the V1 response
|
|
153
|
+
// byte-for-byte. The triples themselves are memory content and are not
|
|
154
|
+
// echoed back (hard rule 6).
|
|
155
|
+
factIds: written.factIds,
|
|
108
156
|
}));
|
|
109
157
|
return ok(output);
|
|
110
158
|
},
|
|
111
159
|
};
|
|
112
160
|
/**
|
|
113
161
|
* get_facts — currently-valid facts for a subject, bi-temporally (docs/concepts/mcp-design.mdx
|
|
114
|
-
* JTBD "what is currently true about X")
|
|
115
|
-
*
|
|
116
|
-
*
|
|
162
|
+
* JTBD "what is currently true about X"), OR a chronological time-series read
|
|
163
|
+
* across a valid-time window (`range`). Calls core getFacts() with the
|
|
164
|
+
* subject/predicate filters and either the as_of coordinates or the range
|
|
165
|
+
* bounds (ISO strings coerced to Date at this boundary) — `range` and `asOf`
|
|
166
|
+
* are mutually exclusive, enforced by factsQueryInputV2Schema.
|
|
167
|
+
*
|
|
168
|
+
* get_facts has NO scope axis (issue #47, reaffirmed for the range read): the
|
|
169
|
+
* facts table carries no scope column, so a range read is not policy-enforced
|
|
170
|
+
* either — deliberately deferred again, not silently dropped.
|
|
117
171
|
*/
|
|
118
172
|
const getFactsTool = {
|
|
119
173
|
name: 'get_facts',
|
|
120
174
|
requiredScope: MEMORY_READ_SCOPE,
|
|
121
175
|
config: {
|
|
122
176
|
title: 'Get Facts',
|
|
123
|
-
description: 'Currently-valid facts for a subject, with optional bi-temporal time travel. List mode (no subject) returns the most recent facts, bounded by an optional limit (default 50, max 200).',
|
|
124
|
-
inputSchema:
|
|
177
|
+
description: 'Currently-valid facts for a subject, with optional bi-temporal time travel, OR a chronological time-series read across a valid-time window (range: {from?, to?} — half-open [from, to), surfaces superseded generations inside it). range and asOf are mutually exclusive. List/range mode (no subject) returns the most recent (or earliest-in-window) facts, bounded by an optional limit (default 50, max 200).',
|
|
178
|
+
inputSchema: factsQueryInputV2Schema,
|
|
125
179
|
outputSchema: factsToolOutputSchema,
|
|
180
|
+
annotations: READ_ONLY_ANNOTATIONS,
|
|
126
181
|
},
|
|
127
182
|
async handler(args, ctx) {
|
|
128
|
-
const input =
|
|
183
|
+
const input = factsQueryInputV2Schema.parse(args);
|
|
129
184
|
// ACCESS GUARD: get_facts is a READ, so read access is asserted BEFORE the db
|
|
130
185
|
// op (self-host allowAllAccess allows all; back-compat when no gate is wired).
|
|
131
186
|
// Mirrors search (which asserts this inside core) and the REST /api/v1/facts
|
|
@@ -136,6 +191,7 @@ const getFactsTool = {
|
|
|
136
191
|
subject: input.subject,
|
|
137
192
|
predicate: input.predicate,
|
|
138
193
|
asOf: toAsOf(input.asOf),
|
|
194
|
+
range: toRange(input.range),
|
|
139
195
|
// Always forward the bounded limit (schema default 50, max 200) so list
|
|
140
196
|
// mode never returns every fact (no-firehose, docs/concepts/mcp-design.mdx).
|
|
141
197
|
limit: input.limit,
|
|
@@ -149,6 +205,7 @@ const getFactsTool = {
|
|
|
149
205
|
confidence: fact.confidence,
|
|
150
206
|
validFrom: fact.validFrom.toISOString(),
|
|
151
207
|
validTo: fact.validTo?.toISOString() ?? null,
|
|
208
|
+
recordedAt: fact.recordedAt.toISOString(),
|
|
152
209
|
})),
|
|
153
210
|
count: facts.length,
|
|
154
211
|
});
|
|
@@ -183,6 +240,19 @@ const reviseTool = {
|
|
|
183
240
|
// key is rejected, never silently stripped.
|
|
184
241
|
inputSchema: reviseToolInputSchema,
|
|
185
242
|
outputSchema: reviseToolOutputSchema,
|
|
243
|
+
// destructiveHint: false is the claim worth making visible. AGENTS.md hard
|
|
244
|
+
// rule 1: no write path destroys memory data. revise closes the
|
|
245
|
+
// predecessor's validity and APPENDS a successor row — the predecessor's
|
|
246
|
+
// content is never rewritten (packages/db/src/memory-revise.ts), and archive
|
|
247
|
+
// moves `status`, not content. Not idempotent: each call appends a new
|
|
248
|
+
// successor, and a repeat against an already-superseded predecessor is a
|
|
249
|
+
// typed rejection rather than a no-op.
|
|
250
|
+
annotations: {
|
|
251
|
+
readOnlyHint: false,
|
|
252
|
+
destructiveHint: false,
|
|
253
|
+
idempotentHint: false,
|
|
254
|
+
openWorldHint: false,
|
|
255
|
+
},
|
|
186
256
|
},
|
|
187
257
|
async handler(args, ctx) {
|
|
188
258
|
// core revise() is THE validation boundary; pass args straight through. It
|
|
@@ -229,6 +299,17 @@ const resolveTool = {
|
|
|
229
299
|
description: 'Settle a memory by its id. A commitment transitions to a target status (open, waiting, resolved, expired) — serves resolve and unresolve (resolved -> open); illegal transitions are rejected. A blocker is archived (status active -> archived) and leaves the active-blocker briefing; the passed status is ignored for blockers and the result reports archived. Commitments AND blockers must be written WITH a project to be resolvable from a project-scoped briefing.',
|
|
230
300
|
inputSchema: resolveToolInputSchema,
|
|
231
301
|
outputSchema: resolveToolOutputSchema,
|
|
302
|
+
// A transition to a TARGET state, not a delta, so repeating it lands on the
|
|
303
|
+
// same state — idempotentHint: true. (An illegal repeat is rejected by the
|
|
304
|
+
// FSM rather than applied twice, which is the same guarantee from the
|
|
305
|
+
// client's side: no second effect.) Archiving a blocker moves `status`; the
|
|
306
|
+
// memory row is untouched, so destructiveHint stays false.
|
|
307
|
+
annotations: {
|
|
308
|
+
readOnlyHint: false,
|
|
309
|
+
destructiveHint: false,
|
|
310
|
+
idempotentHint: true,
|
|
311
|
+
openWorldHint: false,
|
|
312
|
+
},
|
|
232
313
|
},
|
|
233
314
|
async handler(args, ctx) {
|
|
234
315
|
const input = resolveToolInputSchema.parse(args);
|
|
@@ -274,7 +355,16 @@ export const TOOLS = [
|
|
|
274
355
|
// surface (itself included) without a circular import.
|
|
275
356
|
...createAdminTools(() => TOOLS.map((t) => t.name)),
|
|
276
357
|
];
|
|
277
|
-
/**
|
|
358
|
+
/**
|
|
359
|
+
* Working ceiling per docs/concepts/mcp-design.mdx / hard rule 8. LEDGER: 11/12
|
|
360
|
+
* registered, and the twelfth is UNRESERVED — it goes to whichever tool next
|
|
361
|
+
* earns it on the JTBD + evidence test.
|
|
362
|
+
*
|
|
363
|
+
* The number is 3ngram's own, not the protocol's: the 2026-07-28 specification
|
|
364
|
+
* defines no maximum tool count and paginates `tools/list`. What it proxies for
|
|
365
|
+
* is description overlap and model selection accuracy, which is what to argue
|
|
366
|
+
* about when this binds. See docs/concepts/mcp-surface.mdx.
|
|
367
|
+
*/
|
|
278
368
|
export const MAX_TOOLS = 12;
|
|
279
369
|
/**
|
|
280
370
|
* Run a tool handler with uniform metrics + typed-error mapping. A KNOWN typed
|
package/dist/mcp/tools.js.map
CHANGED
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"tools.js","sourceRoot":"","sources":["../../src/mcp/tools.ts"],"names":[],"mappings":"AAAA,sCAAsC;AACtC,gFAAgF;AAChF,qEAAqE;AACrE,yEAAyE;AACzE,gFAAgF;AAChF,4EAA4E;AAC5E,6CAA6C;AAC7C,EAAE;AACF,6FAA6F;AAC7F,4EAA4E;AAC5E,6EAA6E;AAC7E,mCAAmC;AACnC,EAAE;AACF,gFAAgF;AAChF,8EAA8E;AAC9E,kEAAkE;AAClE,OAAO,EAAE,GAAG,EAAE,YAAY,EAAE,aAAa,EAAE,MAAM,gBAAgB,CAAA;AACjE,OAAO,EAGL,QAAQ,EAGR,QAAQ,EACR,iBAAiB,EACjB,MAAM,GACP,MAAM,cAAc,CAAA;AACrB,OAAO,EAAE,iBAAiB,EAAE,kBAAkB,EAAoB,MAAM,mBAAmB,CAAA;AAE3F,OAAO,
|
|
1
|
+
{"version":3,"file":"tools.js","sourceRoot":"","sources":["../../src/mcp/tools.ts"],"names":[],"mappings":"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"}
|
|
@@ -8,6 +8,22 @@
|
|
|
8
8
|
import { bindContext, mcpHeaderRequests } from '@3ngram/config';
|
|
9
9
|
import { PROMPTS } from '../mcp/prompts.js';
|
|
10
10
|
import { TOOLS } from '../mcp/tools.js';
|
|
11
|
+
/**
|
|
12
|
+
* Every MCP method this server actually serves. The set is an ALLOWLIST for
|
|
13
|
+
* metric labels, not a router: an unrecognized value collapses to the literal
|
|
14
|
+
* `'unknown'` so an attacker-controlled header can never open the label
|
|
15
|
+
* cardinality.
|
|
16
|
+
*
|
|
17
|
+
* EXTEND THIS ALONGSIDE ANY NEWLY SERVED METHOD — this is the coupling nobody
|
|
18
|
+
* remembers, and its failure mode is the quiet kind. Real traffic for a method
|
|
19
|
+
* missing here is labelled `unknown_method`: nothing errors, no test goes red,
|
|
20
|
+
* the dashboard simply under-reports the new surface while looking healthy.
|
|
21
|
+
*
|
|
22
|
+
* The `resources/*` and `completion/complete` entries below arrived with issues
|
|
23
|
+
* #105 and #104, each in the PR that started serving it — never earlier, since
|
|
24
|
+
* listing a method the server answers with `-32601` would mislabel the resulting
|
|
25
|
+
* traffic as recognized.
|
|
26
|
+
*/
|
|
11
27
|
const KNOWN_METHODS = new Set([
|
|
12
28
|
'server/discover',
|
|
13
29
|
'initialize',
|
|
@@ -16,6 +32,13 @@ const KNOWN_METHODS = new Set([
|
|
|
16
32
|
'tools/call',
|
|
17
33
|
'prompts/list',
|
|
18
34
|
'prompts/get',
|
|
35
|
+
'resources/templates/list',
|
|
36
|
+
'resources/read',
|
|
37
|
+
// Served (the SDK answers it) but always empty: the memory template registers
|
|
38
|
+
// `list: undefined`, so enumeration returns nothing. It is allowlisted anyway
|
|
39
|
+
// — a client that probes it produces real traffic worth labelling correctly.
|
|
40
|
+
'resources/list',
|
|
41
|
+
'completion/complete',
|
|
19
42
|
]);
|
|
20
43
|
const TOOL_NAMES = new Set(TOOLS.map((tool) => tool.name));
|
|
21
44
|
const PROMPT_NAMES = new Set(PROMPTS.map((prompt) => prompt.name));
|
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"mcp-header-observability.js","sourceRoot":"","sources":["../../src/middleware/mcp-header-observability.ts"],"names":[],"mappings":"AAAA,sCAAsC;AACtC,sEAAsE;AACtE,EAAE;AACF,0EAA0E;AAC1E,0EAA0E;AAC1E,2EAA2E;AAC3E,mDAAmD;AACnD,OAAO,EAAE,WAAW,EAAE,iBAAiB,EAAE,MAAM,gBAAgB,CAAA;AAE/D,OAAO,EAAE,OAAO,EAAE,MAAM,mBAAmB,CAAA;AAC3C,OAAO,EAAE,KAAK,EAAE,MAAM,iBAAiB,CAAA;AAEvC,MAAM,aAAa,GAAG,IAAI,GAAG,CAAC;IAC5B,iBAAiB;IACjB,YAAY;IACZ,MAAM;IACN,YAAY;IACZ,YAAY;IACZ,cAAc;IACd,aAAa;
|
|
1
|
+
{"version":3,"file":"mcp-header-observability.js","sourceRoot":"","sources":["../../src/middleware/mcp-header-observability.ts"],"names":[],"mappings":"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"}
|
|
@@ -0,0 +1,14 @@
|
|
|
1
|
+
import type { NextFunction, Request, Response } from 'express';
|
|
2
|
+
/**
|
|
3
|
+
* Reject a /mcp request whose Origin is present and not allowlisted. Mounted
|
|
4
|
+
* FIRST on the /mcp route — ahead of oauthBearerAuth and the per-user limiter —
|
|
5
|
+
* so a foreign origin never reaches authentication and never consumes a
|
|
6
|
+
* rate-limit point.
|
|
7
|
+
*
|
|
8
|
+
* The allowlist itself lives in @3ngram/config (WEB_APP_URL ∪
|
|
9
|
+
* MCP_ALLOWED_ORIGINS); this middleware holds no policy of its own beyond the
|
|
10
|
+
* present/absent branch. With nothing configured the allowlist is empty and
|
|
11
|
+
* every present Origin is rejected — fail-closed, and harmless for the
|
|
12
|
+
* non-browser clients that send none.
|
|
13
|
+
*/
|
|
14
|
+
export declare function mcpOriginValidation(req: Request, res: Response, next: NextFunction): void;
|
|
@@ -0,0 +1,65 @@
|
|
|
1
|
+
// SPDX-License-Identifier: Apache-2.0
|
|
2
|
+
// Origin validation for /mcp (MCP Streamable HTTP, revision 2026-07-28).
|
|
3
|
+
//
|
|
4
|
+
// THE SPEC RULE: "Servers MUST validate the Origin header on all incoming
|
|
5
|
+
// connections to prevent DNS rebinding attacks. If the Origin header is present
|
|
6
|
+
// and invalid, servers MUST respond with HTTP 403 Forbidden." Note the
|
|
7
|
+
// conditional — PRESENT and invalid. Absence is not a violation, which is what
|
|
8
|
+
// makes the allow-on-absent rule below spec-correct rather than a loophole:
|
|
9
|
+
// non-browser clients (Claude Desktop, the CLI, agent runtimes) send no Origin,
|
|
10
|
+
// and rejecting on absence would break every real client.
|
|
11
|
+
//
|
|
12
|
+
// WHY HAND-ROLLED: the SDK exports originValidationResponse, but it operates on
|
|
13
|
+
// a web Request and this deployment reaches the handler through toNodeHandler +
|
|
14
|
+
// Express. Adapting it would mean constructing a throwaway Request per call for
|
|
15
|
+
// what is one string comparison.
|
|
16
|
+
//
|
|
17
|
+
// HOST IS DELIBERATELY NOT VALIDATED. Only Origin is a MUST. Behind Railway's
|
|
18
|
+
// proxy the Host header is the public hostname, but internal health probes and
|
|
19
|
+
// self-host reverse proxies legitimately present others, so validating it would
|
|
20
|
+
// 403 real traffic for no added protection — /mcp is bearer-only with no cookie
|
|
21
|
+
// or ambient credential, so a rebinding attacker gains nothing to begin with.
|
|
22
|
+
// This is a decision, not an oversight; revisit it only if /mcp ever accepts an
|
|
23
|
+
// ambient credential.
|
|
24
|
+
//
|
|
25
|
+
// OBSERVABILITY: the Origin header is attacker-controlled, so only the OUTCOME
|
|
26
|
+
// is logged, never the raw value — the same posture mcp-header-observability.ts
|
|
27
|
+
// takes toward Mcp-Method / Mcp-Name.
|
|
28
|
+
import { isAllowedMcpOrigin, log } from '@3ngram/config';
|
|
29
|
+
/**
|
|
30
|
+
* JSON-RPC error body for a rejected origin. Carries `id: null` because the
|
|
31
|
+
* request is refused BEFORE the body is trusted as a JSON-RPC message, so there
|
|
32
|
+
* is no request id to echo — the shape the spec permits for a transport-level
|
|
33
|
+
* rejection. `-32600` is Invalid Request.
|
|
34
|
+
*/
|
|
35
|
+
const FORBIDDEN_BODY = {
|
|
36
|
+
jsonrpc: '2.0',
|
|
37
|
+
id: null,
|
|
38
|
+
error: { code: -32_600, message: 'Origin not allowed' },
|
|
39
|
+
};
|
|
40
|
+
/**
|
|
41
|
+
* Reject a /mcp request whose Origin is present and not allowlisted. Mounted
|
|
42
|
+
* FIRST on the /mcp route — ahead of oauthBearerAuth and the per-user limiter —
|
|
43
|
+
* so a foreign origin never reaches authentication and never consumes a
|
|
44
|
+
* rate-limit point.
|
|
45
|
+
*
|
|
46
|
+
* The allowlist itself lives in @3ngram/config (WEB_APP_URL ∪
|
|
47
|
+
* MCP_ALLOWED_ORIGINS); this middleware holds no policy of its own beyond the
|
|
48
|
+
* present/absent branch. With nothing configured the allowlist is empty and
|
|
49
|
+
* every present Origin is rejected — fail-closed, and harmless for the
|
|
50
|
+
* non-browser clients that send none.
|
|
51
|
+
*/
|
|
52
|
+
export function mcpOriginValidation(req, res, next) {
|
|
53
|
+
const origin = req.header('origin');
|
|
54
|
+
if (origin === undefined) {
|
|
55
|
+
next();
|
|
56
|
+
return;
|
|
57
|
+
}
|
|
58
|
+
if (isAllowedMcpOrigin(origin)) {
|
|
59
|
+
next();
|
|
60
|
+
return;
|
|
61
|
+
}
|
|
62
|
+
log().warn({ surface: 'mcp' }, 'mcp: rejected request from a non-allowlisted origin');
|
|
63
|
+
res.status(403).json(FORBIDDEN_BODY);
|
|
64
|
+
}
|
|
65
|
+
//# sourceMappingURL=mcp-origin.js.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"mcp-origin.js","sourceRoot":"","sources":["../../src/middleware/mcp-origin.ts"],"names":[],"mappings":"AAAA,sCAAsC;AACtC,yEAAyE;AACzE,EAAE;AACF,0EAA0E;AAC1E,gFAAgF;AAChF,uEAAuE;AACvE,+EAA+E;AAC/E,4EAA4E;AAC5E,gFAAgF;AAChF,0DAA0D;AAC1D,EAAE;AACF,gFAAgF;AAChF,gFAAgF;AAChF,gFAAgF;AAChF,iCAAiC;AACjC,EAAE;AACF,8EAA8E;AAC9E,+EAA+E;AAC/E,gFAAgF;AAChF,gFAAgF;AAChF,8EAA8E;AAC9E,gFAAgF;AAChF,sBAAsB;AACtB,EAAE;AACF,+EAA+E;AAC/E,gFAAgF;AAChF,sCAAsC;AACtC,OAAO,EAAE,kBAAkB,EAAE,GAAG,EAAE,MAAM,gBAAgB,CAAA;AAGxD;;;;;GAKG;AACH,MAAM,cAAc,GAAG;IACrB,OAAO,EAAE,KAAK;IACd,EAAE,EAAE,IAAI;IACR,KAAK,EAAE,EAAE,IAAI,EAAE,CAAC,MAAM,EAAE,OAAO,EAAE,oBAAoB,EAAE;CAC/C,CAAA;AAEV;;;;;;;;;;;GAWG;AACH,MAAM,UAAU,mBAAmB,CAAC,GAAY,EAAE,GAAa,EAAE,IAAkB;IACjF,MAAM,MAAM,GAAG,GAAG,CAAC,MAAM,CAAC,QAAQ,CAAC,CAAA;IACnC,IAAI,MAAM,KAAK,SAAS,EAAE,CAAC;QACzB,IAAI,EAAE,CAAA;QACN,OAAM;IACR,CAAC;IACD,IAAI,kBAAkB,CAAC,MAAM,CAAC,EAAE,CAAC;QAC/B,IAAI,EAAE,CAAA;QACN,OAAM;IACR,CAAC;IACD,GAAG,EAAE,CAAC,IAAI,CAAC,EAAE,OAAO,EAAE,KAAK,EAAE,EAAE,qDAAqD,CAAC,CAAA;IACrF,GAAG,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC,IAAI,CAAC,cAAc,CAAC,CAAA;AACtC,CAAC"}
|
|
@@ -1,4 +1,4 @@
|
|
|
1
|
-
import type { AsOfInput } from '@3ngram/schema';
|
|
1
|
+
import type { AsOfInput, FactsRangeInput } from '@3ngram/schema';
|
|
2
2
|
import type { Request, Response } from 'express';
|
|
3
3
|
/** Drop undefined values so exact-optional core parameters remain absent. */
|
|
4
4
|
export declare function defined<T extends Record<string, unknown>>(obj: T): {
|
|
@@ -9,6 +9,11 @@ export declare function toAsOf(asOf: AsOfInput | undefined): {
|
|
|
9
9
|
validAt?: Date;
|
|
10
10
|
asKnownAt?: Date;
|
|
11
11
|
} | undefined;
|
|
12
|
+
/** Map an optional {from,to} range's ISO bounds to core Date values (range read). */
|
|
13
|
+
export declare function toRange(range: FactsRangeInput | undefined): {
|
|
14
|
+
from?: Date;
|
|
15
|
+
to?: Date;
|
|
16
|
+
} | undefined;
|
|
12
17
|
/** The authenticated tenant bound by apiOrSessionAuth. */
|
|
13
18
|
export declare function tenant(req: Request): string;
|
|
14
19
|
/** Apply the shared typed-error mapping without logging request content. */
|
|
@@ -17,6 +17,15 @@ export function toAsOf(asOf) {
|
|
|
17
17
|
asKnownAt: asOf.asKnownAt === undefined ? undefined : new Date(asOf.asKnownAt),
|
|
18
18
|
});
|
|
19
19
|
}
|
|
20
|
+
/** Map an optional {from,to} range's ISO bounds to core Date values (range read). */
|
|
21
|
+
export function toRange(range) {
|
|
22
|
+
if (range === undefined)
|
|
23
|
+
return undefined;
|
|
24
|
+
return defined({
|
|
25
|
+
from: range.from === undefined ? undefined : new Date(range.from),
|
|
26
|
+
to: range.to === undefined ? undefined : new Date(range.to),
|
|
27
|
+
});
|
|
28
|
+
}
|
|
20
29
|
/** The authenticated tenant bound by apiOrSessionAuth. */
|
|
21
30
|
export function tenant(req) {
|
|
22
31
|
return req.userId;
|
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"route-helpers.js","sourceRoot":"","sources":["../../src/rest/route-helpers.ts"],"names":[],"mappings":"AAAA,sCAAsC;AACtC,wEAAwE;AACxE,6EAA6E;AAC7E,OAAO,EAAE,GAAG,EAAE,MAAM,gBAAgB,CAAA;AACpC,OAAO,EAAE,cAAc,EAAE,MAAM,qBAAqB,CAAA;AAGpD,OAAO,EAAE,YAAY,EAAE,MAAM,aAAa,CAAA;AAE1C,6EAA6E;AAC7E,MAAM,UAAU,OAAO,CACrB,GAAM;IAEN,OAAO,MAAM,CAAC,WAAW,CAAC,MAAM,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,KAAK,CAAC,EAAE,EAAE,CAAC,KAAK,KAAK,SAAS,CAAC,CAEvF,CAAA;AACH,CAAC;AAED,wDAAwD;AACxD,MAAM,UAAU,MAAM,CACpB,IAA2B;IAE3B,IAAI,IAAI,KAAK,SAAS;QAAE,OAAO,SAAS,CAAA;IACxC,OAAO,OAAO,CAAC;QACb,OAAO,EAAE,IAAI,CAAC,OAAO,KAAK,SAAS,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,IAAI,IAAI,CAAC,IAAI,CAAC,OAAO,CAAC;QACxE,SAAS,EAAE,IAAI,CAAC,SAAS,KAAK,SAAS,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,IAAI,IAAI,CAAC,IAAI,CAAC,SAAS,CAAC;KAC/E,CAAC,CAAA;AACJ,CAAC;AAED,0DAA0D;AAC1D,MAAM,UAAU,MAAM,CAAC,GAAY;IACjC,OAAO,GAAG,CAAC,MAAgB,CAAA;AAC7B,CAAC;AAED,4EAA4E;AAC5E,MAAM,CAAC,KAAK,UAAU,KAAK,CACzB,KAAa,EACb,GAAa,EACb,OAA4B;IAE5B,IAAI,CAAC;QACH,MAAM,OAAO,EAAE,CAAA;IACjB,CAAC;IAAC,OAAO,GAAG,EAAE,CAAC;QACb,MAAM,MAAM,GAAG,YAAY,CAAC,KAAK,EAAE,GAAG,CAAC,CAAA;QACvC,IAAI,MAAM,KAAK,SAAS,EAAE,CAAC;YACzB,GAAG,CAAC,MAAM,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC,IAAI,CAAC,OAAO,CAAC,EAAE,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,CAAC,CAAC,CAAA;YACxF,OAAM;QACR,CAAC;QACD,GAAG,EAAE,CAAC,KAAK,CAAC,EAAE,KAAK,EAAE,GAAG,cAAc,CAAC,GAAG,CAAC,EAAE,EAAE,sBAAsB,CAAC,CAAA;QACtE,IAAI,CAAC,GAAG,CAAC,WAAW;YAAE,GAAG,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC,IAAI,CAAC,EAAE,KAAK,EAAE,gBAAgB,EAAE,CAAC,CAAA;IACzE,CAAC;AACH,CAAC"}
|
|
1
|
+
{"version":3,"file":"route-helpers.js","sourceRoot":"","sources":["../../src/rest/route-helpers.ts"],"names":[],"mappings":"AAAA,sCAAsC;AACtC,wEAAwE;AACxE,6EAA6E;AAC7E,OAAO,EAAE,GAAG,EAAE,MAAM,gBAAgB,CAAA;AACpC,OAAO,EAAE,cAAc,EAAE,MAAM,qBAAqB,CAAA;AAGpD,OAAO,EAAE,YAAY,EAAE,MAAM,aAAa,CAAA;AAE1C,6EAA6E;AAC7E,MAAM,UAAU,OAAO,CACrB,GAAM;IAEN,OAAO,MAAM,CAAC,WAAW,CAAC,MAAM,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,KAAK,CAAC,EAAE,EAAE,CAAC,KAAK,KAAK,SAAS,CAAC,CAEvF,CAAA;AACH,CAAC;AAED,wDAAwD;AACxD,MAAM,UAAU,MAAM,CACpB,IAA2B;IAE3B,IAAI,IAAI,KAAK,SAAS;QAAE,OAAO,SAAS,CAAA;IACxC,OAAO,OAAO,CAAC;QACb,OAAO,EAAE,IAAI,CAAC,OAAO,KAAK,SAAS,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,IAAI,IAAI,CAAC,IAAI,CAAC,OAAO,CAAC;QACxE,SAAS,EAAE,IAAI,CAAC,SAAS,KAAK,SAAS,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,IAAI,IAAI,CAAC,IAAI,CAAC,SAAS,CAAC;KAC/E,CAAC,CAAA;AACJ,CAAC;AAED,qFAAqF;AACrF,MAAM,UAAU,OAAO,CACrB,KAAkC;IAElC,IAAI,KAAK,KAAK,SAAS;QAAE,OAAO,SAAS,CAAA;IACzC,OAAO,OAAO,CAAC;QACb,IAAI,EAAE,KAAK,CAAC,IAAI,KAAK,SAAS,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,IAAI,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC;QACjE,EAAE,EAAE,KAAK,CAAC,EAAE,KAAK,SAAS,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,IAAI,IAAI,CAAC,KAAK,CAAC,EAAE,CAAC;KAC5D,CAAC,CAAA;AACJ,CAAC;AAED,0DAA0D;AAC1D,MAAM,UAAU,MAAM,CAAC,GAAY;IACjC,OAAO,GAAG,CAAC,MAAgB,CAAA;AAC7B,CAAC;AAED,4EAA4E;AAC5E,MAAM,CAAC,KAAK,UAAU,KAAK,CACzB,KAAa,EACb,GAAa,EACb,OAA4B;IAE5B,IAAI,CAAC;QACH,MAAM,OAAO,EAAE,CAAA;IACjB,CAAC;IAAC,OAAO,GAAG,EAAE,CAAC;QACb,MAAM,MAAM,GAAG,YAAY,CAAC,KAAK,EAAE,GAAG,CAAC,CAAA;QACvC,IAAI,MAAM,KAAK,SAAS,EAAE,CAAC;YACzB,GAAG,CAAC,MAAM,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC,IAAI,CAAC,OAAO,CAAC,EAAE,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,CAAC,CAAC,CAAA;YACxF,OAAM;QACR,CAAC;QACD,GAAG,EAAE,CAAC,KAAK,CAAC,EAAE,KAAK,EAAE,GAAG,cAAc,CAAC,GAAG,CAAC,EAAE,EAAE,sBAAsB,CAAC,CAAA;QACtE,IAAI,CAAC,GAAG,CAAC,WAAW;YAAE,GAAG,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC,IAAI,CAAC,EAAE,KAAK,EAAE,gBAAgB,EAAE,CAAC,CAAA;IACzE,CAAC;AACH,CAAC"}
|