semiotic

repository·main·Indexed 25 days ago

https://github.com/nteract/semiotic

A React data visualization library for AI-assisted development, providing verified generative visualizations with deterministic chart validation, repair, and rendering evidence. It supports complex visualizations like network graphs and coordinated dashboards via machine-readable schemas for LLMs and includes an MCP server for integration with agents and clients like Claude Code and ChatGPT.

Tokens
81.8K
Snippets
194
Records
438
Agent score
83%

What's inside semiotic

  1. Use the Semiotic Trust Loop to generate charts

    main

    To ensure charts are valid, accessible, and render correctly, do not hand-write chart JSX. Instead, use the prepareChart function from semiotic/ai. This function validates a chart proposal (component and props) against the provided data and returns either a ready-to-use JSX string and configuration, or reasons for failure along with ranked alternatives for repair.

    In server/SSR contexts, you can inject render: renderChartWithEvidence from semiotic/server to verify that the chart actually renders non-empty content (checking mark counts, domains, and ARIA labels) before serving it.

    import { prepareChart } from "semiotic/ai"
    
    const result = prepareChart(
      { component: "BarChart", props: { data, categoryAccessor: "region", valueAccessor: "revenue" } },
      { data } // supply the data so a poor chart→data fit is caught and alternatives ranked
    )
    
    if (result.ok) {
      // result.jsx is a ready JSX string; result.config is the serializable ChartConfig
    } else {
      // result.reasons explains why; result.repair.alternatives ranks better charts.
      // Retry with a fixed prop or a suggested component — do NOT paint.
    }
  2. Deploy the Semiotic nightly MCP service to Cloud Run

    main

    The semiotic-mcp-nightly service is deployed to us-central1 using the repository's main branch. This deployment uses a two-stage process to ensure the service is host-validated before being made public.

    Prerequisites

    • A valid Google Cloud PROJECT_ID (e.g., semiotic-mcp).
    • An approved RUNTIME_SERVICE_ACCOUNT email.
    • The gcloud CLI installed and configured.

    Manual Deployment Steps

    1. Submit the build: Use gcloud builds submit with the specific configuration file and required substitutions.
    2. Retrieve the hostname: After the build, extract the generated *.run.app URL and hostname.
    3. Verify the service: Run the hosted smoke test to ensure the MCP profile and tools are functioning correctly.
    PROJECT_ID=semiotic-mcp
    GIT_SHA="$(git rev-parse HEAD)"
    RUNTIME_SERVICE_ACCOUNT=APPROVED_RUNTIME_SERVICE_ACCOUNT
    
    gcloud builds submit . \
      --project="$PROJECT_ID" \
      --config=deploy/cloud-run-nightly/cloudbuild.yaml \
      --substitutions="COMMIT_SHA=$GIT_SHA,_TRIGGER_ID=manual,_NIGHTLY_RUNTIME_SERVICE_ACCOUNT=$RUNTIME_SERVICE_ACCOUNT,_NIGHTLY_CPU=1,_NIGHTLY_MEMORY=1Gi,_NIGHTLY_TIMEOUT=300s,_NIGHTLY_CONCURRENCY=80,_NIGHTLY_MIN_INSTANCES=0,_NIGHTLY_MAX_INSTANCES=3,_NIGHTLY_BOOTSTRAP_HOST=bootstrap.invalid"
  3. Configure Semiotic MCP client endpoints

    main

    You can configure both the Stable and Nightly Semiotic MCP channels as distinct servers in your MCP client configuration. Even though they expose the same tool names, they are different servers with different compatibility guarantees. Use the specific service URLs for each channel.

    {
      "mcpServers": {
        "Semiotic": {
          "url": "https://STABLE-SERVICE-URL/mcp"
        },
        "Semiotic Nightly": {
          "url": "https://NIGHTLY-SERVICE-URL/mcp"
        }
      }
    }
  4. Verify a ChatGPT Apps domain

    main

    To verify your domain in the OpenAI domain verification dialog, use the Cloud Run origin URL (not the MCP path).

    1. Provide the Cloud Run origin URL (e.g., https://your-service-url.run.app) in the OpenAI dialog.
    2. Update your Cloud Run service with the provided challenge token using gcloud:
    gcloud run services update <SERVICE_NAME> --region <REGION> \
      --update-env-vars "OPENAI_APPS_CHALLENGE_TOKEN=PASTE_TOKEN_HERE"
    1. Verify the token is being served correctly by performing a curl request to the .well-known endpoint before clicking Verify in the OpenAI dashboard.
    gcloud run services update semiotic-mcp-server --region us-west1 \
      --update-env-vars "OPENAI_APPS_CHALLENGE_TOKEN=PASTE_TOKEN_HERE"
    
    # Verify before clicking in OpenAI dashboard
    curl https://YOUR-SERVICE-URL.run.app/.well-known/openai-apps-challenge
  5. Manage chart themes and presets

    main

    Semiotic provides several built-in themes and a way to resolve them by name:

    • Presets: LIGHT_THEME, DARK_THEME, HIGH_CONTRAST_THEME.
    • Resolution: Use resolveThemePreset(name: string) to retrieve a theme by its name from THEME_PRESETS.
    • React Integration: Use the ThemeProvider component to provide a theme to a component tree.
    • Hooks: Use useTheme() within React components to access the current theme.
    function resolveThemePreset(name: string): SemioticTheme | undefined
    
    function ThemeProvider({ theme, children }: ThemeProviderProps): React.JSX.Element
    
    function useTheme(): SemioticTheme
  6. Generate chatgpt-app-submission.json for ChatGPT Apps

    main

    Use this skill to automate the creation of a chatgpt-app-submission.json file required for ChatGPT Apps submissions. The skill inspects an MCP server codebase to suggest App Info, justify tool annotations (hints), and generate positive and negative test cases.

    Workflow:

    1. The skill inspects the MCP server codebase (metadata, README, manifests, tool descriptors, and implementations).
    2. It validates tool annotations against actual code behavior.
    3. It generates a chatgpt-app-submission.json file in the current working directory.
    4. It reports review-check findings (like missing outputSchema or sensitive data solicitation) in the final response.
    {
      "$schema": "https://developers.openai.com/apps-sdk/schemas/chatgpt-app-submission.v1.json",
      "schema_version": 1,
      "app_info": {
        "display_name": "Example App",
        "subtitle": "Find and update records",
        "description": "Example App helps users find records, inspect details, and update workspace data through ChatGPT.",
        "category": "PRODUCTIVITY"
      },
      "tools": {
        "tool_name": {
          "annotations": {
            "readOnlyHint": true,
            "openWorldHint": false,
            "destructiveHint": false
          },
          "justifications": {
            "read_only_justification": "Only retrieves matching records and does not modify data.",
            "open_world_justification": "Does not write to public internet state or third-party systems.",
            "destructive_justification": "Does not delete, overwrite, revoke access, or perform irreversible actions."
          }
        }
      },
      "test_cases": [
        {
          "description": "Find records that match a specific user request.",
          "user_prompt": "Find my open records for this week.",
          "file_attachment_urls": null,
          "tools_triggered": "tool_name",
          "expected_output": "Returns matching records with enough detail for the user to choose the next action.",
          "expected_output_url": null
        }
      ],
      "negative_test_cases": [
        {
          "description": "Do not trigger for unrelated calendar requests.",
          "user_prompt": "What meetings do I have tomorrow?",
          "file_attachment_urls": null,
          "tools_triggered": null,
          "expected_output": "The app should not be invoked because the request is outside its supported workflows.",
          "expected_output_url": null
        }
      ]
    }
  7. Use Semiotic for AI-assisted development

    main

    Semiotic provides several tools optimized for LLM code generation and validation:

    • semiotic/ai: A single import containing a schema-backed chart capability catalog (XY, ordinal, network, realtime, geo, value). Note: This is a pre-bundled entry point. For production code, use family subpaths like semiotic/xy or semiotic/geo to reduce bundle size.
    • npx semiotic-mcp: An MCP server for tool-based chart rendering in MCP clients.
    • npx semiotic-ai --doctor: A CLI tool to validate component props against JSON schemas with typo suggestions and anti-pattern detection.
    • diagnoseConfig(component, props): A programmatic function to detect anti-patterns in validation, encoding, accessibility, and design.
    • auditData(component, props, data?): A chart-aware numeric preflight that checks for non-finite values, zero-span domains, invalid log inputs, and other mathematical issues.
  8. Deploy Semiotic MCP to Google Cloud Run

    main

    Deploy the stable Semiotic MCP server to Google Cloud Run as a public, remote MCP server. This wrapper runs the semiotic-mcp server in HTTP (Streamable HTTP) mode using the --profile public flag, which exposes only the five task-oriented tools: createChart, improveChart, explainChart, auditChart, and getChartSchema.

    Prerequisites:

    • gcloud CLI installed and configured.
    • A clean environment for deployment.

    Basic Deployment Command: Run the following from the deploy/cloud-run directory to perform a standard deployment. Note that the first run will prompt you to enable Cloud Run, Cloud Build, and Artifact Registry APIs.

    cd deploy/cloud-run
    gcloud run deploy semiotic-mcp-server --source . --region us-west1 \
      --allow-unauthenticated --memory 1Gi \
      --set-env-vars "MCP_ALLOWED_HOSTS=YOUR_CLOUD_RUN_HOSTNAME"
    cd deploy/cloud-run
    gcloud run deploy semiotic-mcp-server --source . --region us-west1 \
      --allow-unauthenticated --memory 1Gi \
      --set-env-vars "MCP_ALLOWED_HOSTS=semiotic-mcp-server-481507046413.us-west1.run.app"
  9. Run Browser and Visual Regression Tests with Playwright

    main

    Visual regression and browser behavior tests are handled by Playwright. Note that these tests typically run against the dist output.

    • Standard run: Use npm run test:dist (requires building dist first).
    • Create new snapshots: Use npm run test:visual:bootstrap to intentionally create missing baseline snapshots.
    • Update existing snapshots: Use npm run test:visual:update to intentionally update existing snapshots.

    Warning: Ordinary local and CI runs use updateSnapshots: "none". A missing baseline will cause a failure rather than writing to the worktree unless the bootstrap command is used. Snapshot baselines are platform-specific (e.g., Linux vs macOS).

    # Build and run visual tests
    npm run dist
    npm run test:dist
    
    # Intentional snapshot management
    npm run test:visual:bootstrap
    npm run test:visual:update
  10. Modify Semiotic library or documentation source

    main

    Modifying the Library (src/)

    1. Edit files in src/.
    2. Run focused tests: npx vitest run path/to/file.test.tsx.
    3. Rebuild the distribution if testing packaged consumers or MCP: npm run dist.
    4. Verify types: npm run typescript.

    Modifying the Documentation (docs/src/)

    1. Edit files in docs/src/.
    2. Run the dev server: npm run docs:dev.
    3. When adding new pages, check routes and coverage: npm run check:docs-routes.
  11. Locate Semiotic documentation for AI assistants

    main

    Semiotic is indexed by several AI-coding-agent documentation tools. If you are using an assistant like Claude Code, Cursor, Cline, or Copilot, they can pull current docs and tools from these sources:

    • Context7: context7.com/nteract/semiotic
    • DeepWiki: deepwiki.com/nteract/semiotic
    • GitMCP: gitmcp.io/nteract/semiotic
    • Official MCP Registry: Search "semiotic" at registry.modelcontextprotocol.io

    Additionally, agents that install Semiotic locally can read the following bundled files directly:

    • CLAUDE.md: Quick-start cheat sheet.
    • ai/schema.json: JSON Schema for every chart's prop surface.
    • ai/surface-manifest.json: Generated inventory of tools and exports.
    • ai/behaviorContracts.cjs: Semantic rules for color precedence and prop combinations.

    For web-based agents, documentation is available via the llms.txt standard at semiotic.nteract.io/llms.txt.