@vampsieee/techterrain-mcp 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025-2026 Romulus (https://techterrain.io)
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,95 @@
+# @vampsieee/techterrain-mcp
+
+An [MCP server](https://modelcontextprotocol.io) that lets AI agents explore **3.4 million years of technology history** through [TechTerrain](https://techterrain.io) — a 3D voxel timeline of 1,200+ curated milestones.
+
+Capture screenshots, generate GIFs, search any topic, and analyze cross-domain patterns — all from Claude, OpenClaw, or any MCP-compatible client.
+
+## Install
+
+```bash
+npx -y @vampsieee/techterrain-mcp
+```
+
+No API key required. The server connects to the public TechTerrain API at techterrain.io.
+
+## Claude Desktop
+
+Add to `~/Library/Application Support/Claude/claude_desktop_config.json` (macOS) or `%APPDATA%\Claude\claude_desktop_config.json` (Windows):
+
+```json
+{
+  "mcpServers": {
+    "techterrain": {
+      "command": "npx",
+      "args": ["-y", "@vampsieee/techterrain-mcp"]
+    }
+  }
+}
+```
+
+Restart Claude Desktop. You'll see the hammer icon with 7 tools.
+
+## Try It
+
+> "Explore quantum computing on TechTerrain and take a screenshot"
+
+> "Show me how AI and biotech have co-evolved, then generate a GIF orbiting the scene"
+
+> "What causal relationships exist between technology categories?"
+
+## Tools
+
+| Tool | Description | Cost |
+|------|-------------|------|
+| `capture_screenshot` | Headless screenshot via Cloudflare Browser Rendering → CDN URL | Free (35/hr) |
+| `capture_gif` | Animated GIF generation (orbit or timelapse) → async job | Free (35/hr) |
+| `get_gif_status` | Poll async GIF job progress and get result URL | Free |
+| `explore_topic` | Search any topic → mapped milestones with years, categories, impact | LLM cost |
+| `generate_insights` | LLM pattern analysis of a scene descriptor | LLM cost |
+| `list_captures` | Browse the Agent Showcase gallery | Free |
+| `get_insights` | Pre-computed Granger causality findings | Free |
+
+## Resources
+
+| Resource | URI | Description |
+|----------|-----|-------------|
+| Agent API Docs | `techterrain://docs` | Full API reference with code examples |
+| LLM Documentation | `techterrain://llms.txt` | Concise API reference for LLMs |
+| Dataset | `techterrain://dataset` | Raw milestone dataset (1,200+ entries) |
+
+## Example Workflow
+
+```
+User: "Show me how AI and biotech have co-evolved"
+
+Agent:
+1. explore_topic("AI biotech co-evolution")
+   → Gets 15 milestones mapped across both categories
+2. capture_screenshot({
+     injectJs: "window.__techterrain.navigate({goto: 2010, categories: ['AI', 'Health']})",
+     caption: "AI-Biotech convergence 2010s"
+   })
+   → Gets CDN URL of the rendered view
+3. get_insights({ limit: 5 })
+   → Gets pre-computed causal findings about AI↔Health correlations
+4. Returns: image, milestones, and statistical insights to user
+```
+
+## Environment Variables
+
+| Variable | Default | Description |
+|----------|---------|-------------|
+| `TECHTERRAIN_URL` | `https://techterrain.io` | Base URL of the TechTerrain instance |
+
+## Development
+
+```bash
+cd mcp
+pnpm install
+npm run dev      # Run with tsx (hot reload)
+npm run build    # Build distributable
+```
+
+## License
+
+MIT

package/dist/index.js

@@ -0,0 +1,336 @@
+#!/usr/bin/env node
+
+// techterrain-mcp-server.ts
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { z } from "zod";
+var BASE_URL = process.env.TECHTERRAIN_URL || "https://techterrain.io";
+var TRPC_URL = `${BASE_URL}/api/trpc`;
+async function trpcMutate(procedure, input) {
+  const res = await fetch(`${TRPC_URL}/${procedure}?batch=1`, {
+    method: "POST",
+    headers: { "Content-Type": "application/json" },
+    body: JSON.stringify({ "0": { json: input } })
+  });
+  if (!res.ok) {
+    const text = await res.text();
+    throw new Error(`tRPC ${procedure} failed (${res.status}): ${text}`);
+  }
+  const batch = await res.json();
+  if (batch[0]?.error) {
+    throw new Error(`tRPC ${procedure} error: ${JSON.stringify(batch[0].error)}`);
+  }
+  return batch[0]?.result?.data?.json;
+}
+async function trpcQuery(procedure, input) {
+  const inputParam = input ? `&input=${encodeURIComponent(JSON.stringify({ "0": { json: input } }))}` : `&input=${encodeURIComponent(JSON.stringify({ "0": { json: void 0 } }))}`;
+  const res = await fetch(`${TRPC_URL}/${procedure}?batch=1${inputParam}`, {
+    method: "GET",
+    headers: { "Content-Type": "application/json" }
+  });
+  if (!res.ok) {
+    const text = await res.text();
+    throw new Error(`tRPC ${procedure} failed (${res.status}): ${text}`);
+  }
+  const batch = await res.json();
+  if (batch[0]?.error) {
+    throw new Error(`tRPC ${procedure} error: ${JSON.stringify(batch[0].error)}`);
+  }
+  return batch[0]?.result?.data?.json;
+}
+async function fetchText(path) {
+  const res = await fetch(`${BASE_URL}${path}`);
+  if (!res.ok) throw new Error(`Failed to fetch ${path}: ${res.status}`);
+  return res.text();
+}
+var server = new McpServer({
+  name: "techterrain",
+  version: "1.0.0"
+});
+server.resource(
+  "docs",
+  "techterrain://docs",
+  {
+    description: "TechTerrain Agent API documentation \u2014 full reference with code examples for all endpoints",
+    mimeType: "text/html"
+  },
+  async () => ({
+    contents: [{
+      uri: "techterrain://docs",
+      text: await fetchText("/agent-docs.html"),
+      mimeType: "text/html"
+    }]
+  })
+);
+server.resource(
+  "llms-txt",
+  "techterrain://llms.txt",
+  {
+    description: "LLM-optimized documentation for TechTerrain \u2014 concise API reference, recommended workflows, and data coverage",
+    mimeType: "text/plain"
+  },
+  async () => ({
+    contents: [{
+      uri: "techterrain://llms.txt",
+      text: await fetchText("/llms.txt"),
+      mimeType: "text/plain"
+    }]
+  })
+);
+server.resource(
+  "dataset",
+  "techterrain://dataset",
+  {
+    description: "Raw TechTerrain milestone dataset \u2014 1,200+ curated technology milestones across 7 categories spanning 3.4 million years",
+    mimeType: "application/json"
+  },
+  async () => ({
+    contents: [{
+      uri: "techterrain://dataset",
+      text: await fetchText("/tech_data.json"),
+      mimeType: "application/json"
+    }]
+  })
+);
+server.tool(
+  "capture_screenshot",
+  `Render a headless screenshot of TechTerrain via Cloudflare Browser Rendering.
+Returns a public CDN URL of the captured image. No client-side browser needed.
+Use injectJs to position the camera, navigate to a year, or trigger UI actions before capture.
+Rate limit: 35 renders/hour.`,
+  {
+    path: z.string().default("/").describe('URL path, e.g. "/" or "/explore/1900-2020/Computing,AI"'),
+    width: z.number().min(320).max(3840).default(1280).describe("Viewport width in pixels"),
+    height: z.number().min(240).max(2160).default(720).describe("Viewport height in pixels"),
+    format: z.enum(["png", "jpeg"]).default("png").describe("Image format"),
+    injectJs: z.string().optional().describe('JavaScript to inject after scene ready. Example: "window.__techterrain.navigate({goto: 1969})"'),
+    waitForOverlays: z.boolean().default(false).describe("Wait for search overlay data to finish loading before capture (set true when injectJs triggers a search)"),
+    caption: z.string().optional().describe("Caption for the showcase gallery"),
+    authorName: z.string().optional().describe("Author name for attribution")
+  },
+  async (args) => {
+    try {
+      const result = await trpcMutate("agent.renderUrl", args);
+      return {
+        content: [{
+          type: "text",
+          text: JSON.stringify({
+            success: true,
+            imageUrl: result.url,
+            browserMsUsed: result.browserMsUsed,
+            message: "Screenshot captured and uploaded to CDN."
+          }, null, 2)
+        }]
+      };
+    } catch (err) {
+      return {
+        content: [{ type: "text", text: `Error: ${err.message}` }],
+        isError: true
+      };
+    }
+  }
+);
+server.tool(
+  "capture_gif",
+  `Generate an animated GIF of TechTerrain via server-side Cloudflare Browser Rendering.
+Returns a jobId immediately \u2014 poll with get_gif_status to check completion.
+Two modes: "orbit" rotates the camera around the scene, "timeLapse" scrubs through years.
+Rate limit: 35 renders/hour (each frame counts as one render).`,
+  {
+    path: z.string().default("/").describe("URL path to render"),
+    mode: z.enum(["orbit", "timeLapse"]).default("orbit").describe("orbit = camera rotation, timeLapse = year scrubbing"),
+    frameCount: z.number().min(2).max(24).default(12).describe("Number of frames in the GIF"),
+    totalRotationDeg: z.number().min(10).max(360).default(360).describe("Total camera rotation in degrees (orbit mode only)"),
+    startYear: z.number().optional().describe("Start year for timeLapse mode (supports negative/BCE values like -3400000)"),
+    endYear: z.number().optional().describe("End year for timeLapse mode"),
+    width: z.number().min(320).max(1920).default(800).describe("Frame width in pixels"),
+    height: z.number().min(240).max(1080).default(600).describe("Frame height in pixels"),
+    frameDelay: z.number().min(50).max(2e3).default(200).describe("Delay between frames in ms"),
+    injectJs: z.string().optional().describe("JavaScript to inject before capture begins"),
+    caption: z.string().optional().describe("Caption for the showcase gallery"),
+    authorName: z.string().optional().describe("Author name for attribution")
+  },
+  async (args) => {
+    try {
+      const result = await trpcMutate("agent.renderGif", args);
+      return {
+        content: [{
+          type: "text",
+          text: JSON.stringify({
+            success: true,
+            jobId: result.jobId,
+            status: result.status,
+            message: "GIF generation started. Poll with get_gif_status tool using this jobId."
+          }, null, 2)
+        }]
+      };
+    } catch (err) {
+      return {
+        content: [{ type: "text", text: `Error: ${err.message}` }],
+        isError: true
+      };
+    }
+  }
+);
+server.tool(
+  "get_gif_status",
+  `Poll the status of an async GIF generation job.
+Returns progress percentage, frames captured, and the final CDN URL when complete.`,
+  {
+    jobId: z.string().describe("The jobId returned by capture_gif")
+  },
+  async (args) => {
+    try {
+      const result = await trpcQuery("agent.renderGifStatus", args);
+      return {
+        content: [{
+          type: "text",
+          text: JSON.stringify({
+            jobId: result.jobId,
+            status: result.status,
+            progress: `${result.progress}%`,
+            framesCaptured: result.framesCaptured,
+            framesTotalRequested: result.framesTotalRequested,
+            ...result.resultUrl ? { gifUrl: result.resultUrl } : {},
+            ...result.browserMsUsed ? { browserMsUsed: result.browserMsUsed } : {},
+            ...result.errorMessage ? { error: result.errorMessage } : {}
+          }, null, 2)
+        }]
+      };
+    } catch (err) {
+      return {
+        content: [{ type: "text", text: `Error: ${err.message}` }],
+        isError: true
+      };
+    }
+  }
+);
+server.tool(
+  "explore_topic",
+  `Search any topic and get it mapped onto TechTerrain's timeline.
+Uses LLM synthesis to find relevant technology milestones for any subject \u2014
+people, companies, concepts, events, or scientific fields.
+Returns structured milestone data with years, categories, impact scores, and source URLs.`,
+  {
+    query: z.string().describe('Topic to explore, e.g. "quantum computing", "Nikola Tesla", "CRISPR gene editing"')
+  },
+  async (args) => {
+    try {
+      const result = await trpcMutate("search.explore", { query: args.query });
+      return {
+        content: [{
+          type: "text",
+          text: JSON.stringify({
+            query: result.query,
+            summary: result.summary,
+            milestoneCount: result.milestones.length,
+            milestones: result.milestones
+          }, null, 2)
+        }]
+      };
+    } catch (err) {
+      return {
+        content: [{ type: "text", text: `Error: ${err.message}` }],
+        isError: true
+      };
+    }
+  }
+);
+server.tool(
+  "generate_insights",
+  `Generate LLM-powered pattern analysis from a TechTerrain scene descriptor.
+Pass the output of getSceneDescriptor() to get cross-domain correlations,
+geographic clustering patterns, and acceleration/deceleration insights.
+Each insight includes confidence rating and suggested camera view.`,
+  {
+    sceneDescriptor: z.any().describe("Scene descriptor JSON from window.__techterrain.getSceneDescriptor()"),
+    focusArea: z.string().optional().describe('Optional focus, e.g. "cross-category correlations" or "geographic clustering"')
+  },
+  async (args) => {
+    try {
+      const result = await trpcMutate("agent.generateInsights", args);
+      return {
+        content: [{
+          type: "text",
+          text: JSON.stringify(result, null, 2)
+        }]
+      };
+    } catch (err) {
+      return {
+        content: [{ type: "text", text: `Error: ${err.message}` }],
+        isError: true
+      };
+    }
+  }
+);
+server.tool(
+  "list_captures",
+  `Browse the TechTerrain Agent Showcase gallery.
+Returns recent agent-generated screenshots and GIFs with metadata, captions, and CDN URLs.`,
+  {
+    type: z.enum(["screenshot", "gif", "render", "all"]).default("all").describe("Filter by capture type"),
+    featuredOnly: z.boolean().default(false).describe("Only return featured captures"),
+    limit: z.number().min(1).max(50).default(20).describe("Number of captures to return")
+  },
+  async (args) => {
+    try {
+      const result = await trpcQuery("agent.listCaptures", args);
+      return {
+        content: [{
+          type: "text",
+          text: JSON.stringify({
+            total: result.total,
+            captures: result.captures.map((c) => ({
+              id: c.id,
+              imageUrl: c.url,
+              type: c.captureType,
+              author: c.authorName,
+              caption: c.caption,
+              featured: c.featured
+            }))
+          }, null, 2)
+        }]
+      };
+    } catch (err) {
+      return {
+        content: [{ type: "text", text: `Error: ${err.message}` }],
+        isError: true
+      };
+    }
+  }
+);
+server.tool(
+  "get_insights",
+  `Get pre-computed Granger causality findings from TechTerrain's Insights Engine.
+Returns statistically significant causal relationships between technology categories
+and economic indicators, with human-readable narrations.
+Free \u2014 no LLM cost (findings are pre-computed via batch analysis).`,
+  {
+    limit: z.number().min(1).max(50).default(10).describe("Number of findings to return")
+  },
+  async (args) => {
+    try {
+      const result = await trpcQuery("insights.getLatest", { limit: args.limit });
+      return {
+        content: [{
+          type: "text",
+          text: JSON.stringify(result, null, 2)
+        }]
+      };
+    } catch (err) {
+      return {
+        content: [{ type: "text", text: `Error: ${err.message}` }],
+        isError: true
+      };
+    }
+  }
+);
+async function main() {
+  const transport = new StdioServerTransport();
+  await server.connect(transport);
+  console.error("TechTerrain MCP server running on stdio");
+}
+main().catch((err) => {
+  console.error("Fatal error:", err);
+  process.exit(1);
+});

package/package.json

@@ -0,0 +1,52 @@
+{
+  "name": "@vampsieee/techterrain-mcp",
+  "version": "1.0.0",
+  "description": "MCP server for TechTerrain — explore 3.4 million years of technology history through AI agents",
+  "type": "module",
+  "main": "dist/index.js",
+  "bin": {
+    "techterrain-mcp": "dist/index.js"
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE",
+    "server.json"
+  ],
+  "scripts": {
+    "build": "esbuild techterrain-mcp-server.ts --bundle --platform=node --format=esm --target=node18 --outfile=dist/index.js --banner:js='#!/usr/bin/env node' --packages=external",
+    "start": "node dist/index.js",
+    "dev": "npx tsx techterrain-mcp-server.ts",
+    "prepublishOnly": "npm run build"
+  },
+  "keywords": [
+    "mcp",
+    "model-context-protocol",
+    "techterrain",
+    "data-visualization",
+    "technology-history",
+    "ai-agent",
+    "claude",
+    "timeline"
+  ],
+  "author": "Romulus (https://techterrain.io)",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/vampsieee/tech-terrain-voxel.git",
+    "directory": "mcp"
+  },
+  "homepage": "https://techterrain.io",
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.26.0",
+    "zod": "^4.1.12"
+  },
+  "devDependencies": {
+    "esbuild": "^0.25.0",
+    "tsx": "^4.0.0",
+    "typescript": "^5.9.0"
+  }
+}

package/server.json

@@ -0,0 +1,76 @@
+{
+  "$schema": "https://registry.modelcontextprotocol.io/schemas/server.json",
+  "name": "techterrain",
+  "display_name": "TechTerrain",
+  "description": "Explore 3.4 million years of technology history through AI agents. Capture screenshots, generate GIFs, search topics, and analyze patterns across 1,200+ curated milestones in a 3D voxel timeline.",
+  "homepage": "https://techterrain.io",
+  "repository": "https://github.com/vampsieee/tech-terrain-voxel",
+  "icon": "https://techterrain.io/favicon.ico",
+  "category": "data-visualization",
+  "tags": [
+    "data-visualization",
+    "technology-history",
+    "timeline",
+    "3d",
+    "voxel",
+    "screenshot",
+    "gif",
+    "research",
+    "education"
+  ],
+  "installations": {
+    "npm": {
+      "type": "npm",
+      "package_name": "@vampsieee/techterrain-mcp",
+      "command": "npx",
+      "args": ["-y", "@vampsieee/techterrain-mcp"]
+    }
+  },
+  "tools": [
+    {
+      "name": "capture_screenshot",
+      "description": "Render a headless screenshot of TechTerrain via Cloudflare Browser Rendering. Returns a public CDN URL."
+    },
+    {
+      "name": "capture_gif",
+      "description": "Generate an animated GIF (orbit or timelapse). Returns a jobId for async polling."
+    },
+    {
+      "name": "get_gif_status",
+      "description": "Poll the status of an async GIF generation job."
+    },
+    {
+      "name": "explore_topic",
+      "description": "Search any topic and get it mapped onto TechTerrain's timeline with structured milestone data."
+    },
+    {
+      "name": "generate_insights",
+      "description": "LLM-powered pattern analysis of a TechTerrain scene descriptor."
+    },
+    {
+      "name": "list_captures",
+      "description": "Browse the Agent Showcase gallery of agent-generated screenshots and GIFs."
+    },
+    {
+      "name": "get_insights",
+      "description": "Get pre-computed Granger causality findings between technology categories and economic indicators."
+    }
+  ],
+  "resources": [
+    {
+      "name": "docs",
+      "uri": "techterrain://docs",
+      "description": "Full Agent API documentation with code examples"
+    },
+    {
+      "name": "llms-txt",
+      "uri": "techterrain://llms.txt",
+      "description": "LLM-optimized concise API reference"
+    },
+    {
+      "name": "dataset",
+      "uri": "techterrain://dataset",
+      "description": "Raw milestone dataset — 1,200+ curated technology milestones across 7 categories"
+    }
+  ]
+}