Inspiration
Persistent homology can reveal connected components, loops, and voids in point clouds and images, but most tools assume that the user already knows the right library, data format, and filtration parameters. An AI agent can help with those choices, but a normal website gives the agent only buttons and text to interpret.
I built WebMCP TDA to give the person and the agent the same computational workspace. The person can manipulate the data visually. The agent can call typed topology tools directly. Both see the same inputs and results in the page.
What it does
The human workbench accepts 2D and 3D point clouds as well as images. A person can drag points, enter exact coordinates, choose a Vietoris-Rips, Alpha, or Cech complex, and play the filtration. For images, the page shows the original, grayscale, and binary-mask stages before computing cubical persistence.
Results include feature counts, essential classes, H1 loops, runtime, a persistence diagram, and structured JSON. The point-cloud preview, filtration geometry, and persistence-diagram playhead move together.
The page exposes four WebMCP tools:
tda_get_capabilitiesdescribes supported complexes, parameters, limits, and image inputs.tda_compute_simplicial_persistencecomputes persistence for an agent-supplied 2D or 3D point cloud.tda_compute_cubical_persistenceanalyzes the current image, a bundled photograph, or an agent-supplied scalar grid.tda_get_latest_resultreads the result currently shared by the person and agent.
An agent call updates the visible workbench. This matters because the person can inspect what the agent submitted instead of trusting a hidden computation.
Why WebMCP fits this use case
A point cloud may contain hundreds of coordinates, and a persistence result may contain many intervals. Asking an agent to operate the visual interface would be slow and error prone. WebMCP gives the agent a bounded schema for the real computation while leaving the visual controls available to the person.
The collaboration also works in both directions. A person can upload an image and ask the agent to analyze the current image. An agent can generate a point cloud, compute its persistence, and leave the exact coordinates and result visible for the person to edit or rerun. Without WebMCP, that workflow requires copying arrays between a notebook, a chat, and a visualization tool.
How I built it
The app registers imperative tools with document.modelContext.registerTool. Each tool has a closed JSON schema, safety annotations, runtime validation, and an AbortSignal. Tool calls and human actions use the same runtime and workspace state.
Computation runs locally through an MIT-licensed WebAssembly package in a Web Worker. The interface uses TypeScript, Vite, React, Plotly.js, PlayCanvas, and the companion tda-viz-react library. Cloudflare Pages hosts the static production build.
The browser enforces limits on point count, coordinate magnitude, image dimensions, filtration scale, result count, and worst-case simplex count. Cancellation terminates the active worker so an expensive request cannot leave later computations stuck behind it.
Challenges
The hardest part was keeping the mathematical and visual states consistent. Rips, Cech, and Alpha complexes use different filtration conventions, so the displayed cover radius cannot be treated as the raw filtration value in every case. I also had to keep the point-cloud projection fixed while a filtration plays, preserve the axis origin while points move, and fit persistence-diagram ranges to each result without rescaling during playback.
WebMCP is still an evolving browser API. I tested registration, cleanup, schemas, execution, cancellation, and malformed inputs separately instead of treating tool discovery as proof that everything worked.
What I learned
I learned how much better an agent interaction becomes when the website exposes a small domain API rather than asking the model to infer actions from layout. I also learned that shared state needs to be visible. A correct tool response is not enough when the person cannot inspect the input that produced it.
What is next
The next useful addition is a seeded point-cloud generator with named shapes, sample count, noise, and dimension. It would make agent-generated experiments reproducible without sending large coordinate arrays. I would also add accessible data tables for persistence pairs and continue profiling the large visualization bundles.
Built With
- c++
- cloudflare-pages
- cypress
- emscripten
- gudhi
- javascript
- playcanvas
- plotly.js
- react
- typescript
- vite
- vitest
- web-workers
- webassembly
- webmcp
