ggaction 0.0.8 → 0.0.10

package/src/mcp/adapter.js

@@ -0,0 +1,206 @@
+import { readFileSync } from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+
+import { searchGgaction } from "../../knowledge/task-resolver.js";
+
+const packageRoot = fileURLToPath(new URL("../../", import.meta.url));
+const cardsArtifact = JSON.parse(readFileSync(
+  path.join(packageRoot, "knowledge/action-cards.json"),
+  "utf8"
+));
+const resourcesArtifact = JSON.parse(readFileSync(
+  path.join(packageRoot, "knowledge/mcp-resources.json"),
+  "utf8"
+));
+
+const cards = new Map(cardsArtifact.cards.map(card => [card.name, card]));
+const recipes = new Map(resourcesArtifact.recipes.map(recipe => [recipe.id, recipe]));
+const docs = new Map(resourcesArtifact.docs.map(section => [section.id, section]));
+
+function unique(values) {
+  return [...new Set(values)];
+}
+
+export const SEARCH_TOOL_NAME = "search_ggaction";
+export const OVERVIEW_URI = "ggaction://overview";
+
+export const SEARCH_TOOL = Object.freeze({
+  name: SEARCH_TOOL_NAME,
+  title: "Search ggaction authoring knowledge",
+  description: "Resolve one complete ggaction chart request into a bounded ordered task packet with exact imports, authoring prerequisites, executable immutable steps, terminal unsupported constraints, and explicit unresolved decisions.",
+  inputSchema: Object.freeze({
+    type: "object",
+    additionalProperties: false,
+    required: ["query"],
+    properties: Object.freeze({
+      query: Object.freeze({
+        type: "string",
+        minLength: 1,
+        maxLength: 500,
+        description: "The exact user chart-authoring request, including chart, encodings, guides, layout, and output format. Do not append dataset contents, code scaffolding, or evaluator instructions."
+      })
+    })
+  }),
+  annotations: Object.freeze({
+    readOnlyHint: true,
+    destructiveHint: false,
+    idempotentHint: true,
+    openWorldHint: false
+  })
+});
+
+export class KnowledgeResourceError extends Error {
+  constructor(message) {
+    super(message);
+    this.name = "KnowledgeResourceError";
+  }
+}
+
+function jsonResource(uri, value) {
+  return Object.freeze({
+    uri,
+    mimeType: "application/json",
+    text: JSON.stringify(value)
+  });
+}
+
+function markdownResource(uri, value) {
+  return Object.freeze({
+    uri,
+    mimeType: "text/markdown",
+    text: `${value.text}\n\nCanonical public route: ${value.route}`
+  });
+}
+
+function encodedUri(owner, id) {
+  return `ggaction://${owner}/${encodeURIComponent(id)}`;
+}
+
+function parseResourceUri(uri) {
+  let parsed;
+  try {
+    parsed = new URL(uri);
+  } catch {
+    throw new KnowledgeResourceError(`Invalid knowledge resource URI: ${uri}`);
+  }
+  if (parsed.protocol !== "ggaction:" || parsed.search || parsed.hash) {
+    throw new KnowledgeResourceError(`Unsupported knowledge resource URI: ${uri}`);
+  }
+  const segments = parsed.pathname.split("/").filter(Boolean);
+  return { owner: parsed.hostname, segments };
+}
+
+export function searchGgactionText(query) {
+  return JSON.stringify(searchGgaction(query));
+}
+
+export function docsFallbackResources(packet) {
+  if (!packet || !Array.isArray(packet.unresolved) || packet.unresolved.length === 0) {
+    return [];
+  }
+  for (const entry of packet.unresolved) {
+    if (!Array.isArray(entry.resources) || entry.resources.length === 0) {
+      throw new KnowledgeResourceError(
+        `Unresolved constraint ${entry.constraint ?? "unknown"} has no explicit documentation resource.`
+      );
+    }
+  }
+  const resources = unique(packet.unresolved.flatMap(entry => entry.resources));
+  return resources.map(uri => {
+    const { owner, segments } = parseResourceUri(uri);
+    if (owner !== "docs" || segments.length !== 1) {
+      throw new KnowledgeResourceError(`Invalid unresolved documentation resource: ${uri}`);
+    }
+    const id = decodeURIComponent(segments[0]);
+    const section = docs.get(id);
+    if (!section) {
+      throw new KnowledgeResourceError(`Unknown unresolved documentation resource: ${uri}`);
+    }
+    return Object.freeze({
+      uri,
+      name: section.title,
+      description: `Read only for the unresolved constraint; public route ${section.route}.`,
+      mimeType: "text/markdown"
+    });
+  });
+}
+
+export function listKnowledgeResources() {
+  return [
+    Object.freeze({
+      uri: OVERVIEW_URI,
+      name: resourcesArtifact.overview.title,
+      description: "Small MCP-first routing instructions; no complete documentation preload.",
+      mimeType: "application/json"
+    }),
+    ...resourcesArtifact.recipes.map(recipe => Object.freeze({
+      uri: encodedUri("recipes", recipe.id),
+      name: recipe.title,
+      description: recipe.summary,
+      mimeType: "application/json"
+    }))
+  ];
+}
+
+export function listKnowledgeResourceTemplates() {
+  return [
+    Object.freeze({
+      uriTemplate: "ggaction://actions/{name}",
+      name: "Exact compact action card",
+      description: "Read one exact action card by current public action name.",
+      mimeType: "application/json"
+    }),
+    Object.freeze({
+      uriTemplate: "ggaction://docs/{section}",
+      name: "Unresolved-only bounded documentation section",
+      description: "Read only a section recommended by the latest search_ggaction unresolved result.",
+      mimeType: "text/markdown"
+    })
+  ];
+}
+
+export function readKnowledgeResource(uri, { allowedDocs = [] } = {}) {
+  if (uri === OVERVIEW_URI) {
+    return jsonResource(uri, {
+      schemaVersion: resourcesArtifact.schemaVersion,
+      title: resourcesArtifact.overview.title,
+      text: resourcesArtifact.overview.text
+    });
+  }
+
+  const { owner, segments } = parseResourceUri(uri);
+  if (segments.length !== 1) {
+    throw new KnowledgeResourceError(`Unknown knowledge resource URI: ${uri}`);
+  }
+  const id = decodeURIComponent(segments[0]);
+  if (owner === "actions") {
+    const card = cards.get(id);
+    if (!card) throw new KnowledgeResourceError(`Unknown ggaction action: ${id}`);
+    return jsonResource(uri, card);
+  }
+  if (owner === "recipes") {
+    const recipe = recipes.get(id);
+    if (!recipe) throw new KnowledgeResourceError(`Unknown ggaction recipe: ${id}`);
+    return jsonResource(uri, {
+      schemaVersion: resourcesArtifact.schemaVersion,
+      ...recipe,
+      packet: searchGgaction(recipe.query)
+    });
+  }
+  if (owner === "docs") {
+    if (!new Set(allowedDocs).has(uri)) {
+      throw new KnowledgeResourceError(
+        "Documentation resources are available only when recommended by the latest unresolved search result."
+      );
+    }
+    const section = docs.get(id);
+    if (!section) throw new KnowledgeResourceError(`Unknown docs fallback section: ${id}`);
+    return markdownResource(uri, section);
+  }
+  throw new KnowledgeResourceError(`Unknown knowledge resource URI: ${uri}`);
+}
+
+if (cardsArtifact.schemaVersion !== 1 || resourcesArtifact.schemaVersion !== 2) {
+  throw new Error("MCP action cards must use schemaVersion 1 and resources schemaVersion 2.");
+}

package/src/mcp/cli.js

@@ -0,0 +1,11 @@
+#!/usr/bin/env node
+
+import { runGgactionMcpServer } from "./server.js";
+
+try {
+  await runGgactionMcpServer();
+} catch (error) {
+  const message = error instanceof Error ? error.message : String(error);
+  process.stderr.write(`ggaction MCP failed: ${message}\n`);
+  process.exitCode = 1;
+}

package/src/mcp/server.js

@@ -0,0 +1,101 @@
+import { Server } from "@modelcontextprotocol/sdk/server/index.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import {
+  CallToolRequestSchema,
+  ErrorCode,
+  ListResourcesRequestSchema,
+  ListResourceTemplatesRequestSchema,
+  ListToolsRequestSchema,
+  McpError,
+  ReadResourceRequestSchema
+} from "@modelcontextprotocol/sdk/types.js";
+
+import {
+  docsFallbackResources,
+  KnowledgeResourceError,
+  listKnowledgeResources,
+  listKnowledgeResourceTemplates,
+  readKnowledgeResource,
+  SEARCH_TOOL,
+  SEARCH_TOOL_NAME,
+  searchGgactionText
+} from "./adapter.js";
+
+const SERVER_INFO = Object.freeze({ name: "ggaction", version: "1.0.0" });
+
+function toolError(error) {
+  const message = error instanceof Error ? error.message : String(error);
+  return {
+    content: [{ type: "text", text: JSON.stringify({ error: message }) }],
+    isError: true
+  };
+}
+
+function validateToolArguments(args) {
+  if (!args || typeof args !== "object" || Array.isArray(args)) {
+    throw new TypeError("search_ggaction arguments must be an object with one query string.");
+  }
+  const names = Object.keys(args);
+  if (names.length !== 1 || names[0] !== "query") {
+    throw new TypeError("search_ggaction accepts exactly one argument: query.");
+  }
+  return args.query;
+}
+
+export function createGgactionMcpServer() {
+  const server = new Server(SERVER_INFO, {
+    capabilities: { tools: {}, resources: {} },
+    instructions: "Call search_ggaction once with only the exact user task; do not append dataset contents, code scaffolding, or evaluator instructions. Use authoring imports, initialization, prerequisites, and immutable steps in order. Treat unsupported entries as terminal limitations. Read only the resource URIs attached to unresolved entries. The server is read-only and does not execute chart code."
+  });
+  let allowedDocs = new Set();
+
+  server.setRequestHandler(ListToolsRequestSchema, async () => ({
+    tools: [SEARCH_TOOL]
+  }));
+
+  server.setRequestHandler(CallToolRequestSchema, async request => {
+    if (request.params.name !== SEARCH_TOOL_NAME) {
+      throw new McpError(ErrorCode.InvalidParams, `Unknown tool: ${request.params.name}`);
+    }
+    try {
+      const query = validateToolArguments(request.params.arguments);
+      const text = searchGgactionText(query);
+      const packet = JSON.parse(text);
+      allowedDocs = new Set(docsFallbackResources(packet).map(resource => resource.uri));
+      return { content: [{ type: "text", text }] };
+    } catch (error) {
+      allowedDocs = new Set();
+      return toolError(error);
+    }
+  });
+
+  server.setRequestHandler(ListResourcesRequestSchema, async () => ({
+    resources: listKnowledgeResources()
+  }));
+
+  server.setRequestHandler(ListResourceTemplatesRequestSchema, async () => ({
+    resourceTemplates: listKnowledgeResourceTemplates()
+  }));
+
+  server.setRequestHandler(ReadResourceRequestSchema, async request => {
+    try {
+      const resource = readKnowledgeResource(request.params.uri, {
+        allowedDocs: [...allowedDocs]
+      });
+      return { contents: [resource] };
+    } catch (error) {
+      if (error instanceof KnowledgeResourceError) {
+        throw new McpError(ErrorCode.InvalidParams, error.message);
+      }
+      throw error;
+    }
+  });
+
+  return server;
+}
+
+export async function runGgactionMcpServer() {
+  const server = createGgactionMcpServer();
+  await server.connect(new StdioServerTransport());
+  return server;
+}

package/types/extension.d.ts

@@ -15,6 +15,21 @@ export interface ActionMetadata {
   scope?: "unit" | "composition" | "any";
 }
 
+export interface RegisteredExtensionActions {}
+
+export type RegisteredExtensionAction = (
+  this: ChartProgram,
+  ...args: any[]
+) => ChartProgram;
+
+export interface ExtensionDefinition<
+  TActions extends Readonly<Record<string, RegisteredExtensionAction>> =
+    Readonly<Record<string, RegisteredExtensionAction>>
+> {
+  name: string;
+  actions: TActions;
+}
+
 export function action<TOptions extends ActionOptions = ActionOptions>(
   metadata: ActionMetadata,
   implementation: (this: ChartProgram, options: TOptions) => ChartProgram
@@ -22,3 +37,7 @@ export function action<TOptions extends ActionOptions = ActionOptions>(
   this: TProgram,
   options?: TOptions
 ) => TProgram;
+
+export function registerExtension<
+  TActions extends Readonly<Record<string, RegisteredExtensionAction>>
+>(definition: ExtensionDefinition<TActions>): void;

package/types/program.d.ts

@@ -1,3 +1,5 @@
+import type { RegisteredExtensionActions } from "./extension.js";
+
 export type FieldType = "quantitative" | "temporal" | "ordinal" | "nominal";
 export type GraphicType =
   | "canvas"
@@ -2189,6 +2191,8 @@ export interface EditTitleOptions
   subtitle?: string | false;
 }
 
+export interface ChartProgram extends RegisteredExtensionActions {}
+
 export class ChartProgram {
   constructor(state?: ActionOptions);
   readonly semanticSpec: SemanticSpec;

package/src/actions/coordinates/index.js

@@ -1,5 +0,0 @@
-import { createCoordinate } from "./actions.js";
-
-export function registerCoordinateActions(ProgramClass) {
-  ProgramClass.prototype.createCoordinate = createCoordinate;
-}

package/src/actions/primitives/semanticValue.js

@@ -1 +0,0 @@
-export { validateSemanticValue } from "./semanticValidation/index.js";