@pdpp/mcp-server 0.4.0 → 0.6.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pdpp/mcp-server",
-  "version": "0.4.0",
+  "version": "0.6.0",
   "description": "Local stdio MCP adapter for grant-scoped PDPP reads and event-subscription management.",
   "type": "module",
   "bin": {

package/src/tools.js

@@ -156,6 +156,49 @@ class MalformedExpandLimitError extends Error {
   }
 }
 
+// Thrown when `expand` is requested on a stream whose schema advertises no
+// expand_capabilities. The RS would also reject this with invalid_expand, but
+// the MCP adapter catches it first so the error message names the stream and
+// the canonical fix (consult schema before constructing expand arguments).
+class UnadvertisedExpandError extends Error {
+  constructor(stream, relations) {
+    const relClause = relations.length
+      ? `Relations requested: ${relations.join(', ')}. `
+      : '';
+    super(
+      `Stream '${stream}' has no advertised expand_capabilities. ${relClause}` +
+        "Consult GET /v1/schema (expand_capabilities) before passing expand; " +
+        "unadvertised relations are rejected.",
+    );
+    this.name = 'UnadvertisedExpandError';
+    this.code = 'invalid_expand';
+  }
+}
+
+// Fetch the compact schema for `stream` and throw UnadvertisedExpandError when
+// no expand_capabilities are advertised. Called only when the caller has
+// already supplied an `expand` argument, so the extra RS round-trip is bounded
+// to expand-using calls. The connection_id is forwarded so multi-source grants
+// resolve cleanly.
+async function assertExpandCapabilities(rs, stream, relations, connectionId) {
+  const schemaQuery = { view: 'compact', stream };
+  if (connectionId) schemaQuery.connection_id = connectionId;
+  const schemaResp = await rs.getJson('/v1/schema', { query: schemaQuery });
+  if (!schemaResp.ok) return; // schema unavailable — let RS enforce
+  const schemaDoc = unwrapSchemaBody(schemaResp.body);
+  const streams = schemaDoc?.streams ?? [];
+  // Find any stream row that matches (may be multiple for shared stream names).
+  const matchingStream = Array.isArray(streams)
+    ? streams.find((s) => s && (s.name === stream || s.stream === stream || s.stream_name === stream))
+    : null;
+  if (!matchingStream) return; // unknown stream — let RS enforce
+  const expandCaps = matchingStream.expand_capabilities;
+  const hasExpandCaps = Array.isArray(expandCaps) ? expandCaps.length > 0 : Boolean(expandCaps);
+  if (!hasExpandCaps) {
+    throw new UnadvertisedExpandError(stream, relations);
+  }
+}
+
 // Thrown when a self-contained fetch id embeds one connection while the
 // explicit `connection_id` argument names another. Silently preferring either
 // handle could read the wrong source, so the disagreement is rejected with a
@@ -433,6 +476,9 @@ export function buildTools({ rs, providerUrl }) {
       outputSchema: z.object(READ_OUTPUT_SCHEMA_SHAPE),
       handler: async (args) => {
         const stream = requireSafeName(args?.stream, 'stream');
+        if (Array.isArray(args?.expand) && args.expand.length > 0) {
+          await assertExpandCapabilities(rs, stream, args.expand, args?.connection_id);
+        }
         const query = applyExpandLimitToQuery(
           applyFilterToQuery(pickQuery(args, SUPPORTED_QUERY_KEYS), args?.filter),
           args?.expand_limit,
@@ -449,7 +495,7 @@ export function buildTools({ rs, providerUrl }) {
       name: 'aggregate',
       title: 'Aggregate PDPP records',
       description:
-        'Compute a single-stream aggregation via `GET /v1/streams/{stream}/aggregate`. Prefer over `query_records` when you only need a count, sum, min/max, distinct count, or grouped/time-bucketed rollup — returns small bucket rows, never record bodies. Metrics: `count`, `sum`, `min`, `max`, `count_distinct` (`field` required for all but `count`). Group with one dimension: `group_by` XOR `group_by_time` (requires `granularity`). Groupable fields are advertised by `GET /v1/schema`. Forwards args verbatim. ' +
+        'Compute a single-stream aggregation via `GET /v1/streams/{stream}/aggregate`. Prefer over `query_records` when you only need a count, sum, min/max, distinct count, or grouped/time-bucketed rollup — returns small bucket rows, never record bodies. Metrics: `count`, `sum`, `min`, `max`, `count_distinct` (`field` required for all but `count`). Group with one dimension: `group_by` XOR `group_by_time` (requires `granularity`). Grouped responses include `other_count` (records in groups beyond `limit`) so you can detect top-N truncation without a second call. Groupable fields are advertised by `GET /v1/schema`. Forwards args verbatim. ' +
         CANONICAL_SCHEMA_HINT +
         ' Read-only.',
       annotations: READ_ONLY_ANNOTATIONS,
@@ -565,6 +611,10 @@ export function buildTools({ rs, providerUrl }) {
         if (ref.connectionId && typeof args?.connection_id === 'string' && args.connection_id !== ref.connectionId) {
           throw new ConflictingConnectionIdError(ref.connectionId, args.connection_id);
         }
+        if (Array.isArray(args?.expand) && args.expand.length > 0) {
+          const connId = args?.connection_id ?? ref.connectionId;
+          await assertExpandCapabilities(rs, ref.stream, args.expand, connId);
+        }
         const query = applyExpandLimitToQuery(pickQuery(args, SUPPORTED_QUERY_KEYS), args?.expand_limit);
         // A self-contained id carries its own connection scope; forward it so a
         // multi-source grant resolves without a second model-carried handle.
@@ -1035,7 +1085,8 @@ function summarizeAggregate(body, stream) {
       return `${formatScalar(key)}=${count == null ? '?' : count}`;
     });
     const more = groups.length > AGGREGATE_GROUP_PREVIEW_LIMIT ? ` more_groups=${groups.length - AGGREGATE_GROUP_PREVIEW_LIMIT};` : '';
-    return `${head} ${dimension}: ${groups.length} group(s) [${shown.join(', ')}]${more} canonical envelope in structuredContent.data`;
+    const otherCount = typeof agg.other_count === 'number' ? ` other_count=${agg.other_count};` : '';
+    return `${head} ${dimension}: ${groups.length} group(s) [${shown.join(', ')}]${more}${otherCount} canonical envelope in structuredContent.data`;
   }
 
   // Ungrouped: the scalar answer lives in `value`. Fall back to
@@ -1610,13 +1661,14 @@ function summarizeSearch(body, results) {
   const hasMore = envelopeField(body, 'has_more') === true ? ' has_more=true.' : '';
   const nextCursor = envelopeStringField(body, 'next_cursor');
   const cursorText = nextCursor ? ` next_cursor=${formatScalar(nextCursor)}.` : '';
+  const firstFetchText = results[0]?.id ? ` first_fetch_id=${formatInlineValue(results[0].id)}` : '';
   const sourceMixText = formatSearchSourceMix(body);
   const previews = results.slice(0, SEARCH_TEXT_PREVIEW_LIMIT).map(formatSearchPreviewLine);
   const previewText = previews.length > 0 ? ` Top results:\n${previews.join('\n')}` : '';
   const fetchHint = previews.length > 0
     ? '\nFetch a hit with `fetch` using the shown id as-is; ids are self-contained. Pass connection_id only when shown separately.'
     : '';
-  return `search: ${results.length} hit(s).${hasMore}${cursorText}${sourceMixText}${previewText}${fetchHint} Search envelope metadata: structuredContent.data; flattened results: structuredContent.results.`;
+  return `search: ${results.length} hit(s).${hasMore}${cursorText}${firstFetchText}${sourceMixText}${previewText}${fetchHint} Search envelope metadata: structuredContent.data; flattened results: structuredContent.results.`;
 }
 
 function formatSearchSourceMix(body) {
@@ -2147,4 +2199,6 @@ export const __internal = {
   toFetchToolResult,
   resolveStreamName,
   resolveSchemaDetail,
+  assertExpandCapabilities,
+  UnadvertisedExpandError,
 };