@3ngram/server 1.1.3 → 1.2.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/cursor.d.ts +66 -0
- package/dist/cursor.js +130 -0
- package/dist/cursor.js.map +1 -0
- package/dist/mcp/errors.js +22 -2
- package/dist/mcp/errors.js.map +1 -1
- package/dist/mcp/tools-admin.js +32 -15
- package/dist/mcp/tools-admin.js.map +1 -1
- package/dist/mcp/tools-inspect.d.ts +6 -0
- package/dist/mcp/tools-inspect.js +95 -0
- package/dist/mcp/tools-inspect.js.map +1 -0
- package/dist/mcp/tools-orient.js +38 -18
- package/dist/mcp/tools-orient.js.map +1 -1
- package/dist/mcp/tools-search.d.ts +7 -0
- package/dist/mcp/tools-search.js +188 -0
- package/dist/mcp/tools-search.js.map +1 -0
- package/dist/mcp/tools.d.ts +13 -4
- package/dist/mcp/tools.js +12 -69
- package/dist/mcp/tools.js.map +1 -1
- package/dist/rest/errors.d.ts +6 -0
- package/dist/rest/errors.js +19 -2
- package/dist/rest/errors.js.map +1 -1
- package/dist/rest/route-helpers.d.ts +15 -0
- package/dist/rest/route-helpers.js +40 -0
- package/dist/rest/route-helpers.js.map +1 -0
- package/dist/rest/router.js +59 -130
- package/dist/rest/router.js.map +1 -1
- package/dist/rest/search-router.d.ts +9 -0
- package/dist/rest/search-router.js +118 -0
- package/dist/rest/search-router.js.map +1 -0
- package/dist/routes/mcp.d.ts +1 -1
- package/dist/routes/mcp.js +28 -8
- package/dist/routes/mcp.js.map +1 -1
- package/package.json +4 -4
- package/dist/rest/cursor.d.ts +0 -14
- package/dist/rest/cursor.js +0 -38
- package/dist/rest/cursor.js.map +0 -1
package/dist/cursor.d.ts
ADDED
|
@@ -0,0 +1,66 @@
|
|
|
1
|
+
import { type CursorPayload } from '@3ngram/schema';
|
|
2
|
+
/** Serialize a cursor payload to an opaque base64url token. */
|
|
3
|
+
export declare function encodeCursor(payload: CursorPayload): string;
|
|
4
|
+
/**
|
|
5
|
+
* Decode + validate an opaque cursor token back to its v2 payload.
|
|
6
|
+
*
|
|
7
|
+
* Returns `undefined` for a legacy v1 keyset cursor (`{ s, id }`) minted before
|
|
8
|
+
* the v2 deploy — the caller restarts at page 1 rather than erroring
|
|
9
|
+
* mid-session across the deploy boundary. A genuinely malformed token (bad
|
|
10
|
+
* base64/JSON, or a shape that is neither v2 nor v1) throws a ZodError, which
|
|
11
|
+
* the transport maps to a validation failure (mapRestError -> 400 on REST) — a
|
|
12
|
+
* forged or garbled cursor is client input, never a server crash.
|
|
13
|
+
*/
|
|
14
|
+
export declare function decodeCursor(token: string): CursorPayload | undefined;
|
|
15
|
+
/**
|
|
16
|
+
* A continuation cursor replayed against a DIFFERENT query/filter set than the
|
|
17
|
+
* one that issued it. Typed invalid-input (client mistake): mapped to 400 on
|
|
18
|
+
* REST (mapRestError) / invalid_input on MCP — NEVER silently paging the
|
|
19
|
+
* frozen ids of the old search under the new query. The message carries no
|
|
20
|
+
* query text (hard rule 6).
|
|
21
|
+
*/
|
|
22
|
+
export declare class CursorQueryMismatchError extends Error {
|
|
23
|
+
constructor();
|
|
24
|
+
}
|
|
25
|
+
/**
|
|
26
|
+
* Short stable fingerprint of a search: sha256 over the POST-PARSE query text
|
|
27
|
+
* EXACTLY as given plus the canonicalized effective filter set, truncated to 16 hex
|
|
28
|
+
* chars (64 bits — collision-safe for a mismatch GUARD, not an identifier).
|
|
29
|
+
*
|
|
30
|
+
* NO normalization of the query happens here — deliberately. Both transports
|
|
31
|
+
* call this with the schema-PARSED query, and both query schemas `.trim()` at
|
|
32
|
+
* the one validation boundary (searchQueryV3Schema via searchInputSchema for
|
|
33
|
+
* the MCP tool; dashboardSearchQuerySchema for the REST route), so edge
|
|
34
|
+
* whitespace is already gone by the time the text reaches core OR this hash.
|
|
35
|
+
* Core then embeds that same post-parse text verbatim: the fingerprint hashes
|
|
36
|
+
* EXACTLY what retrieval sees, and a second trim here could only ever DIVERGE
|
|
37
|
+
* from embedding semantics, never align them. Inner whitespace and case
|
|
38
|
+
* change the embedding — "find\nme" and "find me" are DIFFERENT searches and
|
|
39
|
+
* must not fingerprint-collide (collapsing would let a changed query silently
|
|
40
|
+
* reuse the old frozen ordering).
|
|
41
|
+
*
|
|
42
|
+
* `effectiveScope` lets policy-aware callers bind a defaulted scope even when
|
|
43
|
+
* it was absent from the caller's filters. `scopeAppliedByPolicy` additionally
|
|
44
|
+
* distinguishes that default from an explicit caller scope with the same
|
|
45
|
+
* value. The discriminator is appended only when true so fingerprints minted
|
|
46
|
+
* for explicit/no-policy searches before this binding remain compatible;
|
|
47
|
+
* pre-binding policy-default cursors fail closed.
|
|
48
|
+
*
|
|
49
|
+
* Issuance freezes it into the cursor (`fp`); continuation recomputes it from
|
|
50
|
+
* the CURRENT request and verifies via {@link decodeSearchCursor}. The query
|
|
51
|
+
* text itself never leaves this function (hard rule 6: hash only).
|
|
52
|
+
*/
|
|
53
|
+
export declare function searchFingerprint(query: string, filters: Record<string, unknown>, effectiveScope?: string, scopeAppliedByPolicy?: boolean): string;
|
|
54
|
+
/**
|
|
55
|
+
* Decode a search continuation token AND bind it to the current search:
|
|
56
|
+
* {@link decodeCursor} semantics, plus — when the payload carries a
|
|
57
|
+
* fingerprint — verification against the fingerprint of the CURRENT
|
|
58
|
+
* query/filters, throwing {@link CursorQueryMismatchError} on mismatch.
|
|
59
|
+
*
|
|
60
|
+
* COMPATIBILITY (verify-when-present): a fingerprint-less v2 cursor minted
|
|
61
|
+
* before `fp` existed decodes fine and is NOT rejected — verification applies
|
|
62
|
+
* only to cursors that carry the binding. Both transports (REST dashboard
|
|
63
|
+
* route and the MCP search tool) parse continuations through THIS entry point
|
|
64
|
+
* so the binding cannot drift per transport.
|
|
65
|
+
*/
|
|
66
|
+
export declare function decodeSearchCursor(token: string, fingerprint: string): CursorPayload | undefined;
|
package/dist/cursor.js
ADDED
|
@@ -0,0 +1,130 @@
|
|
|
1
|
+
// SPDX-License-Identifier: Apache-2.0
|
|
2
|
+
// Node-side opaque encode/decode for the search frozen-ordering cursor,
|
|
3
|
+
// SHARED by the REST dashboard route (rest/router.ts) and the MCP search tool.
|
|
4
|
+
// The payload SHAPE (cursorPayloadSchema) is the shared contract in
|
|
5
|
+
// @3ngram/schema; the base64url serialization lives here so the schema package
|
|
6
|
+
// stays dependency-light (zod only — no @types/node for Buffer). Clients treat
|
|
7
|
+
// the token as opaque and never decode it (see lib/search/api.ts).
|
|
8
|
+
import { createHash } from 'node:crypto';
|
|
9
|
+
import { cursorPayloadSchema, legacyCursorPayloadSchema } from '@3ngram/schema';
|
|
10
|
+
/** Serialize a cursor payload to an opaque base64url token. */
|
|
11
|
+
export function encodeCursor(payload) {
|
|
12
|
+
return Buffer.from(JSON.stringify(payload), 'utf8').toString('base64url');
|
|
13
|
+
}
|
|
14
|
+
/**
|
|
15
|
+
* Decode + validate an opaque cursor token back to its v2 payload.
|
|
16
|
+
*
|
|
17
|
+
* Returns `undefined` for a legacy v1 keyset cursor (`{ s, id }`) minted before
|
|
18
|
+
* the v2 deploy — the caller restarts at page 1 rather than erroring
|
|
19
|
+
* mid-session across the deploy boundary. A genuinely malformed token (bad
|
|
20
|
+
* base64/JSON, or a shape that is neither v2 nor v1) throws a ZodError, which
|
|
21
|
+
* the transport maps to a validation failure (mapRestError -> 400 on REST) — a
|
|
22
|
+
* forged or garbled cursor is client input, never a server crash.
|
|
23
|
+
*/
|
|
24
|
+
export function decodeCursor(token) {
|
|
25
|
+
let json;
|
|
26
|
+
try {
|
|
27
|
+
json = JSON.parse(Buffer.from(token, 'base64url').toString('utf8'));
|
|
28
|
+
}
|
|
29
|
+
catch {
|
|
30
|
+
json = undefined;
|
|
31
|
+
}
|
|
32
|
+
const v2 = cursorPayloadSchema.safeParse(json);
|
|
33
|
+
if (v2.success)
|
|
34
|
+
return v2.data;
|
|
35
|
+
if (legacyCursorPayloadSchema.safeParse(json).success)
|
|
36
|
+
return undefined;
|
|
37
|
+
// Neither v2 nor a recognized legacy cursor → malformed client input (400).
|
|
38
|
+
return cursorPayloadSchema.parse(json);
|
|
39
|
+
}
|
|
40
|
+
/**
|
|
41
|
+
* A continuation cursor replayed against a DIFFERENT query/filter set than the
|
|
42
|
+
* one that issued it. Typed invalid-input (client mistake): mapped to 400 on
|
|
43
|
+
* REST (mapRestError) / invalid_input on MCP — NEVER silently paging the
|
|
44
|
+
* frozen ids of the old search under the new query. The message carries no
|
|
45
|
+
* query text (hard rule 6).
|
|
46
|
+
*/
|
|
47
|
+
export class CursorQueryMismatchError extends Error {
|
|
48
|
+
constructor() {
|
|
49
|
+
super('cursor was issued for a different query — omit the cursor to start a new search');
|
|
50
|
+
this.name = 'CursorQueryMismatchError';
|
|
51
|
+
}
|
|
52
|
+
}
|
|
53
|
+
/**
|
|
54
|
+
* Canonicalize a filter value for hashing: Dates → ISO strings, object keys
|
|
55
|
+
* sorted, `undefined` entries dropped (an absent filter and an omitted one are
|
|
56
|
+
* the same filter set), and primitive arrays sorted (the only array-valued
|
|
57
|
+
* filter, `memoryTypes`, is an OR-SET — order is not semantic).
|
|
58
|
+
*/
|
|
59
|
+
function canonicalize(value) {
|
|
60
|
+
if (value instanceof Date)
|
|
61
|
+
return value.toISOString();
|
|
62
|
+
if (Array.isArray(value)) {
|
|
63
|
+
const items = value.map(canonicalize);
|
|
64
|
+
return items.every((item) => typeof item === 'string') ? [...items].sort() : items;
|
|
65
|
+
}
|
|
66
|
+
if (typeof value === 'object' && value !== null) {
|
|
67
|
+
return Object.fromEntries(Object.entries(value)
|
|
68
|
+
.filter(([, entry]) => entry !== undefined)
|
|
69
|
+
.sort(([a], [b]) => a.localeCompare(b))
|
|
70
|
+
.map(([key, entry]) => [key, canonicalize(entry)]));
|
|
71
|
+
}
|
|
72
|
+
return value;
|
|
73
|
+
}
|
|
74
|
+
/**
|
|
75
|
+
* Short stable fingerprint of a search: sha256 over the POST-PARSE query text
|
|
76
|
+
* EXACTLY as given plus the canonicalized effective filter set, truncated to 16 hex
|
|
77
|
+
* chars (64 bits — collision-safe for a mismatch GUARD, not an identifier).
|
|
78
|
+
*
|
|
79
|
+
* NO normalization of the query happens here — deliberately. Both transports
|
|
80
|
+
* call this with the schema-PARSED query, and both query schemas `.trim()` at
|
|
81
|
+
* the one validation boundary (searchQueryV3Schema via searchInputSchema for
|
|
82
|
+
* the MCP tool; dashboardSearchQuerySchema for the REST route), so edge
|
|
83
|
+
* whitespace is already gone by the time the text reaches core OR this hash.
|
|
84
|
+
* Core then embeds that same post-parse text verbatim: the fingerprint hashes
|
|
85
|
+
* EXACTLY what retrieval sees, and a second trim here could only ever DIVERGE
|
|
86
|
+
* from embedding semantics, never align them. Inner whitespace and case
|
|
87
|
+
* change the embedding — "find\nme" and "find me" are DIFFERENT searches and
|
|
88
|
+
* must not fingerprint-collide (collapsing would let a changed query silently
|
|
89
|
+
* reuse the old frozen ordering).
|
|
90
|
+
*
|
|
91
|
+
* `effectiveScope` lets policy-aware callers bind a defaulted scope even when
|
|
92
|
+
* it was absent from the caller's filters. `scopeAppliedByPolicy` additionally
|
|
93
|
+
* distinguishes that default from an explicit caller scope with the same
|
|
94
|
+
* value. The discriminator is appended only when true so fingerprints minted
|
|
95
|
+
* for explicit/no-policy searches before this binding remain compatible;
|
|
96
|
+
* pre-binding policy-default cursors fail closed.
|
|
97
|
+
*
|
|
98
|
+
* Issuance freezes it into the cursor (`fp`); continuation recomputes it from
|
|
99
|
+
* the CURRENT request and verifies via {@link decodeSearchCursor}. The query
|
|
100
|
+
* text itself never leaves this function (hard rule 6: hash only).
|
|
101
|
+
*/
|
|
102
|
+
export function searchFingerprint(query, filters, effectiveScope, scopeAppliedByPolicy = false) {
|
|
103
|
+
const boundFilters = effectiveScope === undefined ? filters : { ...filters, scope: effectiveScope };
|
|
104
|
+
const canonicalFilters = JSON.stringify(canonicalize(boundFilters));
|
|
105
|
+
const policyProvenance = scopeAppliedByPolicy ? '\npolicy-scope:applied' : '';
|
|
106
|
+
return createHash('sha256')
|
|
107
|
+
.update(`${query}\n${canonicalFilters}${policyProvenance}`)
|
|
108
|
+
.digest('hex')
|
|
109
|
+
.slice(0, 16);
|
|
110
|
+
}
|
|
111
|
+
/**
|
|
112
|
+
* Decode a search continuation token AND bind it to the current search:
|
|
113
|
+
* {@link decodeCursor} semantics, plus — when the payload carries a
|
|
114
|
+
* fingerprint — verification against the fingerprint of the CURRENT
|
|
115
|
+
* query/filters, throwing {@link CursorQueryMismatchError} on mismatch.
|
|
116
|
+
*
|
|
117
|
+
* COMPATIBILITY (verify-when-present): a fingerprint-less v2 cursor minted
|
|
118
|
+
* before `fp` existed decodes fine and is NOT rejected — verification applies
|
|
119
|
+
* only to cursors that carry the binding. Both transports (REST dashboard
|
|
120
|
+
* route and the MCP search tool) parse continuations through THIS entry point
|
|
121
|
+
* so the binding cannot drift per transport.
|
|
122
|
+
*/
|
|
123
|
+
export function decodeSearchCursor(token, fingerprint) {
|
|
124
|
+
const payload = decodeCursor(token);
|
|
125
|
+
if (payload?.fp !== undefined && payload.fp !== fingerprint) {
|
|
126
|
+
throw new CursorQueryMismatchError();
|
|
127
|
+
}
|
|
128
|
+
return payload;
|
|
129
|
+
}
|
|
130
|
+
//# sourceMappingURL=cursor.js.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"cursor.js","sourceRoot":"","sources":["../src/cursor.ts"],"names":[],"mappings":"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"}
|
package/dist/mcp/errors.js
CHANGED
|
@@ -6,12 +6,13 @@
|
|
|
6
6
|
// memory content, query text, subject/value, or a credential (observability hard
|
|
7
7
|
// rule 6: only the error class name + bounded ids/hashes/enum states).
|
|
8
8
|
import { log, mcpToolErrors } from '@3ngram/config';
|
|
9
|
-
import { AccessDeniedError, BudgetExceededError, CommitmentExistsError, CommitmentNotFoundError, DuplicateMemoryError, EdgeConflictError, EpisodicSupersessionError, IllegalCommitmentTransitionError, InvalidCommitmentTransitionError, InvalidEmbeddingError, MissingSelectorError, NotCommitmentMemoryError, PredecessorAlreadySupersededError, PredecessorNotFoundError,
|
|
9
|
+
import { AccessDeniedError, BudgetExceededError, CommitmentExistsError, CommitmentNotFoundError, DuplicateMemoryError, EdgeConflictError, EpisodicSupersessionError, formatUnscopedRetrievalDetail, IllegalCommitmentTransitionError, InvalidCommitmentTransitionError, InvalidEmbeddingError, MissingSelectorError, NotCommitmentMemoryError, PredecessorAlreadySupersededError, PredecessorNotFoundError,
|
|
10
10
|
// Admin tools: scope registry + proposal review typed errors —
|
|
11
11
|
// appended block. ProposalNotFoundError now also covers the accept path's
|
|
12
12
|
// not-open / not-owned guard.
|
|
13
|
-
ProposalNotFoundError, ResourceLimitExceededError, ScopeNameConflictError, ScopeNotFoundError, SuccessorNotLiveError, } from '@3ngram/core';
|
|
13
|
+
ProposalNotFoundError, ResourceLimitExceededError, ScopeNameConflictError, ScopeNotFoundError, SuccessorNotLiveError, UnscopedRetrievalError, } from '@3ngram/core';
|
|
14
14
|
import { ZodError } from 'zod';
|
|
15
|
+
import { CursorQueryMismatchError } from '../cursor.js';
|
|
15
16
|
import { OutputValidationError } from '../output-validation.js';
|
|
16
17
|
/** Wrap a typed failure as an isError result. The message names the class only. */
|
|
17
18
|
function fail(message) {
|
|
@@ -51,6 +52,25 @@ export function mapToolError(toolName, err) {
|
|
|
51
52
|
log().warn({ tool_name: toolName, err: err.name }, 'mcp: tool input rejected');
|
|
52
53
|
return fail(`invalid input: ${err.name}`);
|
|
53
54
|
}
|
|
55
|
+
// An unscoped read rejected by the caller's own retrieval-scope policy
|
|
56
|
+
// (mode 'require', issue #47) — a MissingSelectorError sibling: a 400-class
|
|
57
|
+
// caller mistake, counted as invalid_input. The bounded recovery names a
|
|
58
|
+
// prefix of the REGISTERED SCOPES (user labels, never memory content — hard
|
|
59
|
+
// rule 6) and reports how many additional names were omitted.
|
|
60
|
+
if (err instanceof UnscopedRetrievalError) {
|
|
61
|
+
mcpToolErrors.add(1, { tool_name: toolName, reason_code: 'invalid_input' });
|
|
62
|
+
log().warn({ tool_name: toolName, err: err.name }, 'mcp: unscoped read rejected by policy');
|
|
63
|
+
return fail(`invalid input: ${formatUnscopedRetrievalDetail(err.registeredScopes)}`);
|
|
64
|
+
}
|
|
65
|
+
// A continuation cursor replayed against a DIFFERENT query/filter set than
|
|
66
|
+
// the one that issued it — the caller's mistake, named honestly with the
|
|
67
|
+
// recovery (never a silent re-page of the old search's frozen ordering, and
|
|
68
|
+
// no query text in the log or the result — hard rule 6).
|
|
69
|
+
if (err instanceof CursorQueryMismatchError) {
|
|
70
|
+
mcpToolErrors.add(1, { tool_name: toolName, reason_code: 'invalid_input' });
|
|
71
|
+
log().warn({ tool_name: toolName, err: err.name }, 'mcp: cursor query mismatch');
|
|
72
|
+
return fail('invalid input: cursor was issued for a different query — omit the cursor to start a new search');
|
|
73
|
+
}
|
|
54
74
|
// Over the per-user budget cap. A documented domain denial,
|
|
55
75
|
// not a server fault: a class-named isError result counted under budget_exceeded.
|
|
56
76
|
// Names ONLY the bounded operation key — never the cap/consumption or any
|
package/dist/mcp/errors.js.map
CHANGED
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"errors.js","sourceRoot":"","sources":["../../src/mcp/errors.ts"],"names":[],"mappings":"AAAA,sCAAsC;AACtC,gFAAgF;AAChF,iFAAiF;AACjF,iFAAiF;AACjF,iFAAiF;AACjF,iFAAiF;AACjF,uEAAuE;AACvE,OAAO,EAAE,GAAG,EAAE,aAAa,EAAE,MAAM,gBAAgB,CAAA;AACnD,OAAO,EACL,iBAAiB,EACjB,mBAAmB,EACnB,qBAAqB,EACrB,uBAAuB,EACvB,oBAAoB,EACpB,iBAAiB,EACjB,yBAAyB,EACzB,gCAAgC,EAChC,gCAAgC,EAChC,qBAAqB,EACrB,oBAAoB,EACpB,wBAAwB,EACxB,iCAAiC,EACjC,wBAAwB;AACxB,+DAA+D;AAC/D,0EAA0E;AAC1E,8BAA8B;AAC9B,qBAAqB,EACrB,0BAA0B,EAC1B,sBAAsB,EACtB,kBAAkB,EAClB,qBAAqB,
|
|
1
|
+
{"version":3,"file":"errors.js","sourceRoot":"","sources":["../../src/mcp/errors.ts"],"names":[],"mappings":"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"}
|
package/dist/mcp/tools-admin.js
CHANGED
|
@@ -27,9 +27,9 @@
|
|
|
27
27
|
// action-discriminated unions are registered without a permissive raw-shape
|
|
28
28
|
// bridge. The exact per-action contract is enforced at the transport boundary.
|
|
29
29
|
import { log, mcpToolErrors } from '@3ngram/config';
|
|
30
|
-
import { applyProposal, createScope, deleteScope, describeEnvironment, listProposals, listScopes, rejectProposal, renameScope, setScopeAliases, } from '@3ngram/core';
|
|
30
|
+
import { applyProposal, createScope, deleteScope, describeEnvironment, listProposals, listScopes, rejectProposal, renameScope, setRetrievalDefault, setScopeAliases, } from '@3ngram/core';
|
|
31
31
|
import { MEMORY_READ_SCOPE, MEMORY_WRITE_SCOPE } from '@3ngram/core/auth';
|
|
32
|
-
import {
|
|
32
|
+
import { configureScopeInputV2Schema, configureScopeOutputV2Schema, describeEnvironmentInputSchema, describeEnvironmentOutputV2Schema, reviewProposalsInputSchema, reviewProposalsOutputSchema, } from '@3ngram/schema';
|
|
33
33
|
import { parseOutput } from '../output-validation.js';
|
|
34
34
|
import { SERVER_VERSION } from '../version.js';
|
|
35
35
|
/** Wrap a structured payload as a tool success result (text mirror + structured). */
|
|
@@ -92,7 +92,7 @@ async function runConfigureScope(input, ctx) {
|
|
|
92
92
|
if (ctx.access)
|
|
93
93
|
await ctx.access.assertRead(ctx.userId);
|
|
94
94
|
const scopes = await listScopes(ctx.userId);
|
|
95
|
-
return ok(parseOutput('configure_scope',
|
|
95
|
+
return ok(parseOutput('configure_scope', configureScopeOutputV2Schema, {
|
|
96
96
|
action: 'list',
|
|
97
97
|
scopes: scopes.map(toScopeOutput),
|
|
98
98
|
count: scopes.length,
|
|
@@ -101,9 +101,9 @@ async function runConfigureScope(input, ctx) {
|
|
|
101
101
|
const denied = requireScope('configure_scope', ctx, MEMORY_WRITE_SCOPE);
|
|
102
102
|
if (denied !== undefined)
|
|
103
103
|
return denied;
|
|
104
|
-
// ACCESS GUARD: every mutating scope action (create/rename/set_aliases/delete
|
|
105
|
-
// a WRITE — write access is asserted BEFORE the db op
|
|
106
|
-
// allows all).
|
|
104
|
+
// ACCESS GUARD: every mutating scope action (create/rename/set_aliases/delete/
|
|
105
|
+
// set_retrieval_default) is a WRITE — write access is asserted BEFORE the db op
|
|
106
|
+
// (self-host allowAllAccess allows all).
|
|
107
107
|
if (ctx.access)
|
|
108
108
|
await ctx.access.assertWrite(ctx.userId);
|
|
109
109
|
switch (input.action) {
|
|
@@ -121,11 +121,25 @@ async function runConfigureScope(input, ctx) {
|
|
|
121
121
|
}
|
|
122
122
|
case 'delete': {
|
|
123
123
|
await deleteScope(ctx.userId, input.name);
|
|
124
|
-
return ok(parseOutput('configure_scope',
|
|
124
|
+
return ok(parseOutput('configure_scope', configureScopeOutputV2Schema, {
|
|
125
125
|
action: 'deleted',
|
|
126
126
|
name: input.name,
|
|
127
127
|
}));
|
|
128
128
|
}
|
|
129
|
+
case 'set_retrieval_default': {
|
|
130
|
+
// Shape consistency (mode↔scope pairing) was enforced by the schema
|
|
131
|
+
// boundary; core asserts the SEMANTIC invariant (a default scope must be
|
|
132
|
+
// REGISTERED -> typed ScopeNotFoundError, mapped by errors.ts) and
|
|
133
|
+
// returns the stored setting, echoed as the policy record.
|
|
134
|
+
const policy = await setRetrievalDefault(ctx.userId, {
|
|
135
|
+
mode: input.mode,
|
|
136
|
+
scope: input.scope,
|
|
137
|
+
});
|
|
138
|
+
return ok(parseOutput('configure_scope', configureScopeOutputV2Schema, {
|
|
139
|
+
action: 'retrieval_default_set',
|
|
140
|
+
policy,
|
|
141
|
+
}));
|
|
142
|
+
}
|
|
129
143
|
default:
|
|
130
144
|
// Exhaustiveness guard: every mutating action is handled above. The strict
|
|
131
145
|
// union makes this unreachable; it pins the compiler to flag a NEW action.
|
|
@@ -133,7 +147,7 @@ async function runConfigureScope(input, ctx) {
|
|
|
133
147
|
}
|
|
134
148
|
}
|
|
135
149
|
function upserted(scope) {
|
|
136
|
-
return ok(parseOutput('configure_scope',
|
|
150
|
+
return ok(parseOutput('configure_scope', configureScopeOutputV2Schema, {
|
|
137
151
|
action: 'upserted',
|
|
138
152
|
scope: toScopeOutput(scope),
|
|
139
153
|
}));
|
|
@@ -196,12 +210,12 @@ export function createAdminTools(toolNames) {
|
|
|
196
210
|
requiredScope: { anyOf: [MEMORY_READ_SCOPE, MEMORY_WRITE_SCOPE] },
|
|
197
211
|
config: {
|
|
198
212
|
title: 'Configure Scope',
|
|
199
|
-
description: 'Manage your memory scopes: list, create, rename, set aliases, or delete (registry only — existing memories keep their scope). Mutating actions require the write scope.',
|
|
200
|
-
inputSchema:
|
|
201
|
-
outputSchema:
|
|
213
|
+
description: 'Manage your memory scopes: list, create, rename, set aliases, or delete (registry only — existing memories keep their scope). set_retrieval_default binds your READS to a scope: mode "default" narrows unscoped search/briefing/handoff calls to the given scope (results report appliedScope), "require" rejects unscoped reads until a scope is passed, "off" restores unrestricted reads (scope must be null for require/off). Mutating actions require the write scope.',
|
|
214
|
+
inputSchema: configureScopeInputV2Schema,
|
|
215
|
+
outputSchema: configureScopeOutputV2Schema,
|
|
202
216
|
},
|
|
203
217
|
async handler(args, ctx) {
|
|
204
|
-
const input =
|
|
218
|
+
const input = configureScopeInputV2Schema.parse(args);
|
|
205
219
|
return runConfigureScope(input, ctx);
|
|
206
220
|
},
|
|
207
221
|
};
|
|
@@ -210,9 +224,9 @@ export function createAdminTools(toolNames) {
|
|
|
210
224
|
requiredScope: MEMORY_READ_SCOPE,
|
|
211
225
|
config: {
|
|
212
226
|
title: 'Describe Environment',
|
|
213
|
-
description: 'Report server capabilities (tool names, count, version), your registered scopes, and bounded memory/commitment counts. Exposes no secrets or configuration values.',
|
|
227
|
+
description: 'Report server capabilities (tool names, count, version), your registered scopes, your active retrieval-scope policy (retrievalScopePolicy), and bounded memory/commitment counts. Exposes no secrets or configuration values.',
|
|
214
228
|
inputSchema: describeEnvironmentInputSchema,
|
|
215
|
-
outputSchema:
|
|
229
|
+
outputSchema: describeEnvironmentOutputV2Schema,
|
|
216
230
|
},
|
|
217
231
|
async handler(args, ctx) {
|
|
218
232
|
describeEnvironmentInputSchema.parse(args);
|
|
@@ -224,9 +238,12 @@ export function createAdminTools(toolNames) {
|
|
|
224
238
|
await ctx.access.assertRead(ctx.userId);
|
|
225
239
|
const report = await describeEnvironment(ctx.userId);
|
|
226
240
|
const names = toolNames();
|
|
227
|
-
const output = parseOutput('describe_environment',
|
|
241
|
+
const output = parseOutput('describe_environment', describeEnvironmentOutputV2Schema, {
|
|
228
242
|
capabilities: { tools: [...names], toolCount: names.length, version: SERVER_VERSION },
|
|
229
243
|
scopes: report.scopes.map(toScopeOutput),
|
|
244
|
+
// The active retrieval-scope policy (issue #47): a bounded mode enum +
|
|
245
|
+
// a registered scope NAME — the redaction posture is unchanged.
|
|
246
|
+
retrievalScopePolicy: report.retrievalScopePolicy,
|
|
230
247
|
stats: {
|
|
231
248
|
memoriesByType: report.stats.memoriesByType,
|
|
232
249
|
activeMemories: report.stats.activeMemories,
|
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"tools-admin.js","sourceRoot":"","sources":["../../src/mcp/tools-admin.ts"],"names":[],"mappings":"AAAA,sCAAsC;AACtC,0DAA0D;AAC1D,6DAA6D;AAC7D,sDAAsD;AACtD,4EAA4E;AAC5E,yCAAyC;AACzC,EAAE;AACF,oEAAoE;AACpE,+EAA+E;AAC/E,iFAAiF;AACjF,gFAAgF;AAChF,iFAAiF;AACjF,iFAAiF;AACjF,0EAA0E;AAC1E,8EAA8E;AAC9E,6EAA6E;AAC7E,gFAAgF;AAChF,gFAAgF;AAChF,+DAA+D;AAC/D,EAAE;AACF,6DAA6D;AAC7D,gFAAgF;AAChF,kFAAkF;AAClF,iDAAiD;AACjD,EAAE;AACF,gFAAgF;AAChF,4EAA4E;AAC5E,+EAA+E;AAC/E,OAAO,EAAE,GAAG,EAAE,aAAa,EAAE,MAAM,gBAAgB,CAAA;AACnD,OAAO,EACL,aAAa,EACb,WAAW,EACX,WAAW,EACX,mBAAmB,EACnB,aAAa,EACb,UAAU,EAEV,cAAc,EACd,WAAW,EAEX,eAAe,GAChB,MAAM,cAAc,CAAA;AACrB,OAAO,EAAE,iBAAiB,EAAE,kBAAkB,EAAoB,MAAM,mBAAmB,CAAA;AAC3F,OAAO,EAEL,
|
|
1
|
+
{"version":3,"file":"tools-admin.js","sourceRoot":"","sources":["../../src/mcp/tools-admin.ts"],"names":[],"mappings":"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"}
|
|
@@ -0,0 +1,6 @@
|
|
|
1
|
+
import type { ToolDefinition } from './tools.js';
|
|
2
|
+
/**
|
|
3
|
+
* The inspect tools, appended to the {@link TOOLS} registry by tools.ts. A
|
|
4
|
+
* readonly array so the registry stays the single auditable surface.
|
|
5
|
+
*/
|
|
6
|
+
export declare const INSPECT_TOOLS: readonly ToolDefinition[];
|
|
@@ -0,0 +1,95 @@
|
|
|
1
|
+
// SPDX-License-Identifier: Apache-2.0
|
|
2
|
+
// MCP INSPECT tool: `get_memories` — the batched full-content follow-up read
|
|
3
|
+
// for ids a search/handoff surfaced with `truncated: true`. A SEPARATE module
|
|
4
|
+
// from the core read/write tools (tools.ts) so the registry file stays thin
|
|
5
|
+
// (500-line cap, tools-orient.ts / tools-admin.ts precedent) — tools.ts only
|
|
6
|
+
// IMPORTS this array and spreads it into TOOLS (append-only).
|
|
7
|
+
//
|
|
8
|
+
// Same THIN-ADAPTER contract as every tool: validate at the ONE boundary
|
|
9
|
+
// (packages/schema Zod), call the COMPLETE core service (which runs withTenant
|
|
10
|
+
// internally), shape the structured result. A read -> requiredScope
|
|
11
|
+
// memory:read; runTool enforces the scope BEFORE the handler runs.
|
|
12
|
+
//
|
|
13
|
+
// OUTPUT DISCIPLINE (docs/concepts/mcp-design.mdx): content is bounded
|
|
14
|
+
// PER ITEM at the caller-requested `maxContentChars` (default 10,000, ceiling
|
|
15
|
+
// 65,536 — import rows reach 262,144 chars and must never ride back verbatim),
|
|
16
|
+
// the batch is bounded at MAX_GET_MEMORIES_IDS, and the AGGREGATE at
|
|
17
|
+
// MAX_GET_TOTAL_CHARS (ids × maxContentChars ≤ one worst-case import row). A missing or cross-tenant
|
|
18
|
+
// id lands in `notFound` — DATA, never an error: one bad id must not fail the
|
|
19
|
+
// batch, and the collapse of not-found/not-owned (RLS + caller-bound
|
|
20
|
+
// predicate, resolved in core/db) means the result never leaks whether a
|
|
21
|
+
// foreign id exists.
|
|
22
|
+
//
|
|
23
|
+
// CONTENT IN OUTPUT vs LOGS: the OUTPUT carries memory content BY DESIGN (a
|
|
24
|
+
// bounded data export to the authenticated caller, the tool's JTBD). The
|
|
25
|
+
// handler logs nothing; rule 6 (no content in logs/traces/metrics) is upheld.
|
|
26
|
+
import { getMemoriesByIds } from '@3ngram/core';
|
|
27
|
+
import { MEMORY_READ_SCOPE } from '@3ngram/core/auth';
|
|
28
|
+
import { DEFAULT_GET_CONTENT_CHARS, getMemoriesInputSchema, getMemoriesOutputSchema, MAX_GET_CONTENT_CHARS, MAX_GET_MEMORIES_IDS, MAX_GET_TOTAL_CHARS, } from '@3ngram/schema';
|
|
29
|
+
import { parseOutput } from '../output-validation.js';
|
|
30
|
+
/** Wrap a structured payload as a tool success result (text mirror + structured). */
|
|
31
|
+
function ok(structured) {
|
|
32
|
+
return {
|
|
33
|
+
content: [{ type: 'text', text: JSON.stringify(structured) }],
|
|
34
|
+
structuredContent: structured,
|
|
35
|
+
};
|
|
36
|
+
}
|
|
37
|
+
/**
|
|
38
|
+
* get_memories — batched full-content read (docs/concepts/mcp-design.mdx JTBD
|
|
39
|
+
* "read what I found"). Validates the bounded id batch + content cap, calls
|
|
40
|
+
* core getMemoriesByIds() (ONE withTenant, ONE `id = ANY` query — never a
|
|
41
|
+
* per-id loop), and returns `{ memories, count, notFound }`. Dates are ISO
|
|
42
|
+
* strings at this boundary; `commitmentStatus` is included only when the row
|
|
43
|
+
* carries one (the output schema marks it optional, mirroring the REST
|
|
44
|
+
* detail).
|
|
45
|
+
*/
|
|
46
|
+
const getMemoriesTool = {
|
|
47
|
+
name: 'get_memories',
|
|
48
|
+
requiredScope: MEMORY_READ_SCOPE,
|
|
49
|
+
config: {
|
|
50
|
+
title: 'Get Memories',
|
|
51
|
+
description: `Fetch the full content of memories by id — use this after search or handoff returns an item with truncated: true to read the complete body. Accepts up to ${MAX_GET_MEMORIES_IDS} ids plus an optional maxContentChars per-item bound (default ${DEFAULT_GET_CONTENT_CHARS}, max ${MAX_GET_CONTENT_CHARS}; ids × maxContentChars may not exceed ${MAX_GET_TOTAL_CHARS} per call); an item still truncated at the cap reports truncated: true with its full contentLength. Ids that do not resolve for you are listed in notFound — never an error.`,
|
|
52
|
+
inputSchema: getMemoriesInputSchema,
|
|
53
|
+
outputSchema: getMemoriesOutputSchema,
|
|
54
|
+
},
|
|
55
|
+
async handler(args, ctx) {
|
|
56
|
+
const input = getMemoriesInputSchema.parse(args);
|
|
57
|
+
// ACCESS GUARD: get_memories EXPORTS memory content, so read access is
|
|
58
|
+
// asserted BEFORE the db op (self-host allowAllAccess allows all;
|
|
59
|
+
// back-compat when no gate is wired). Mirrors handoff/get_facts.
|
|
60
|
+
if (ctx.access)
|
|
61
|
+
await ctx.access.assertRead(ctx.userId);
|
|
62
|
+
const result = await getMemoriesByIds(ctx.userId, input.ids, {
|
|
63
|
+
maxContentChars: input.maxContentChars,
|
|
64
|
+
});
|
|
65
|
+
const output = parseOutput('get_memories', getMemoriesOutputSchema, {
|
|
66
|
+
memories: result.memories.map((memory) => ({
|
|
67
|
+
id: memory.id,
|
|
68
|
+
memoryType: memory.memoryType,
|
|
69
|
+
topic: memory.topic,
|
|
70
|
+
content: memory.content,
|
|
71
|
+
contentLength: memory.contentLength,
|
|
72
|
+
truncated: memory.truncated,
|
|
73
|
+
scope: memory.scope,
|
|
74
|
+
project: memory.project,
|
|
75
|
+
status: memory.status,
|
|
76
|
+
// Optional in the output schema: present only for a commitment-type
|
|
77
|
+
// memory (REST detail parity); a null LEFT-JOIN miss is omitted.
|
|
78
|
+
...(memory.commitmentStatus != null ? { commitmentStatus: memory.commitmentStatus } : {}),
|
|
79
|
+
tags: memory.tags,
|
|
80
|
+
validFrom: memory.validFrom.toISOString(),
|
|
81
|
+
validTo: memory.validTo?.toISOString() ?? null,
|
|
82
|
+
recordedAt: memory.recordedAt.toISOString(),
|
|
83
|
+
})),
|
|
84
|
+
count: result.memories.length,
|
|
85
|
+
notFound: result.notFound,
|
|
86
|
+
});
|
|
87
|
+
return ok(output);
|
|
88
|
+
},
|
|
89
|
+
};
|
|
90
|
+
/**
|
|
91
|
+
* The inspect tools, appended to the {@link TOOLS} registry by tools.ts. A
|
|
92
|
+
* readonly array so the registry stays the single auditable surface.
|
|
93
|
+
*/
|
|
94
|
+
export const INSPECT_TOOLS = [getMemoriesTool];
|
|
95
|
+
//# sourceMappingURL=tools-inspect.js.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"tools-inspect.js","sourceRoot":"","sources":["../../src/mcp/tools-inspect.ts"],"names":[],"mappings":"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"}
|