@visulima/vis-mcp 0.0.1 → 1.0.0-alpha.1

package/CHANGELOG.md

@@ -0,0 +1,16 @@
+## @visulima/vis-mcp 1.0.0-alpha.1 (2026-05-04)
+
+### Features
+
+* **vis-mcp:** add list_templates and describe_template tools ([549ea7e](https://github.com/visulima/visulima/commit/549ea7edbe88e3dde40e09cf5f5eaea80bb8fd58))
+* **vis-mcp:** add MCP server package for AI-agent integration ([a8d5022](https://github.com/visulima/visulima/commit/a8d5022ba905481985378c0ac01e7f654608ec2b))
+
+### Miscellaneous Chores
+
+* **vis-mcp:** adopt zod v4 catalog and bump @modelcontextprotocol/sdk ([a84ceb1](https://github.com/visulima/visulima/commit/a84ceb1efcfb368c361eb738006f2e7f113ac4c7))
+
+
+### Dependencies
+
+* **@visulima/fs:** upgraded to 5.0.0-alpha.13
+* **@visulima/vis:** upgraded to 1.0.0-alpha.11

package/LICENSE.md

@@ -0,0 +1,27 @@
+MIT License
+
+Copyright (c) 2026 visulima
+
+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.
+
+<!-- DEPENDENCIES -->
+<!-- /DEPENDENCIES -->
+
+<!-- TYPE_DEPENDENCIES -->
+<!-- /TYPE_DEPENDENCIES -->

package/README.md

@@ -1,45 +1,138 @@
-# @visulima/vis-mcp
+<!-- START_PACKAGE_OG_IMAGE_PLACEHOLDER -->
 
-## ⚠️ IMPORTANT NOTICE ⚠️
+<a href="https://www.anolilab.com/open-source" align="center">
 
-**This package is created solely for the purpose of setting up OIDC (OpenID Connect) trusted publishing with npm.**
+  <img src="__assets__/package-og.svg" alt="vis-mcp" />
 
-This is **NOT** a functional package and contains **NO** code or functionality beyond the OIDC setup configuration.
+</a>
 
-## Purpose
+<h3 align="center">MCP (Model Context Protocol) server for @visulima/vis — exposes vis tooling to AI agents over stdio</h3>
 
-This package exists to:
-1. Configure OIDC trusted publishing for the package name `@visulima/vis-mcp`
-2. Enable secure, token-less publishing from CI/CD workflows
-3. Establish provenance for packages published under this name
+<!-- END_PACKAGE_OG_IMAGE_PLACEHOLDER -->
 
-## What is OIDC Trusted Publishing?
+<br />
 
-OIDC trusted publishing allows package maintainers to publish packages directly from their CI/CD workflows without needing to manage npm access tokens. Instead, it uses OpenID Connect to establish trust between the CI/CD provider (like GitHub Actions) and npm.
+<div align="center">
 
-## Setup Instructions
+[![typescript-image][typescript-badge]][typescript-url]
+[![mit licence][license-badge]][license]
+[![npm downloads][npm-downloads-badge]][npm-downloads]
+[![Chat][chat-badge]][chat]
+[![PRs Welcome][prs-welcome-badge]][prs-welcome]
 
-To properly configure OIDC trusted publishing for this package:
+</div>
 
-1. Go to [npmjs.com](https://www.npmjs.com/) and navigate to your package settings
-2. Configure the trusted publisher (e.g., GitHub Actions)
-3. Specify the repository and workflow that should be allowed to publish
-4. Use the configured workflow to publish your actual package
+---
+
+<div align="center">
+    <p>
+        <sup>
+            Daniel Bannert's open source work is supported by the community on <a href="https://github.com/sponsors/prisis">GitHub Sponsors</a>
+        </sup>
+    </p>
+</div>
 
-## DO NOT USE THIS PACKAGE
+---
 
-This package is a placeholder for OIDC configuration only. It:
-- Contains no executable code
-- Provides no functionality
-- Should not be installed as a dependency
-- Exists only for administrative purposes
+## Install
 
-## More Information
+```sh
+npm install @visulima/vis-mcp
+```
 
-For more details about npm's trusted publishing feature, see:
-- [npm Trusted Publishing Documentation](https://docs.npmjs.com/generating-provenance-statements)
-- [GitHub Actions OIDC Documentation](https://docs.github.com/en/actions/deployment/security-hardening-your-deployments/about-security-hardening-with-openid-connect)
+```sh
+yarn add @visulima/vis-mcp
+```
 
----
+```sh
+pnpm add @visulima/vis-mcp
+```
+
+## Usage
+
+`@visulima/vis-mcp` is an MCP (Model Context Protocol) server that exposes a read-only view of your `@visulima/vis` workspace to an LLM agent over stdio. It assumes `@visulima/vis` is installed in the workspace it operates against.
+
+### Run
+
+```sh
+npx @visulima/vis-mcp
+```
+
+The server speaks JSON-RPC on stdout and writes status to stderr. Wire it into any MCP-aware client (Claude Desktop, Cursor, Continue, etc.) by pointing the client at the `vis-mcp` command.
+
+### Claude Desktop config
+
+Add the server to `~/Library/Application Support/Claude/claude_desktop_config.json` (macOS) or `%APPDATA%\Claude\claude_desktop_config.json` (Windows):
+
+```json
+{
+    "mcpServers": {
+        "vis": {
+            "command": "npx",
+            "args": ["-y", "@visulima/vis-mcp"],
+            "env": {
+                "VIS_MCP_WORKSPACE_ROOT": "/absolute/path/to/your/workspace"
+            }
+        }
+    }
+}
+```
+
+### Environment
+
+- `VIS_MCP_WORKSPACE_ROOT` — workspace to operate against. Defaults to `process.cwd()`.
+- `VIS_MCP_VIS_BIN` — explicit path to the `vis` CLI. Defaults to resolving `@visulima/vis` from the workspace's `node_modules`.
+
+### Tools
+
+All eight tools are read-only. The agent prepares commands; a human runs them.
+
+| Tool                | What it does                                                                                           |
+| ------------------- | ------------------------------------------------------------------------------------------------------ |
+| `list_projects`     | List all workspace projects, optionally filtered by a vis query string.                                |
+| `describe_project`  | Return full metadata for one project (language, layer, stack, targets).                                |
+| `list_targets`      | Flatten projects into per-target rows; optionally narrow to one project.                               |
+| `list_templates`    | List scaffolding templates discovered in the workspace, with source and one-line description.          |
+| `describe_template` | Return template metadata: description, default destination, and the variable schema for `vis generate`.|
+| `get_run_logs`      | Read a run summary from `.task-runner/`; optionally filter to one task.                                |
+| `cache_why`         | Diff a task's hash inputs against the previous run to explain a rotation.                              |
+| `cache_hash`        | Print the recorded hash and per-input hash details for a task.                                         |
+
+## Related
+
+## Supported Node.js Versions
+
+Libraries in this ecosystem make the best effort to track [Node.js’ release schedule](https://github.com/nodejs/release#release-schedule).
+Here’s [a post on why we think this is important](https://medium.com/the-node-js-collection/maintainers-should-consider-following-node-js-release-schedule-ab08ed4de71a).
+
+## Contributing
+
+If you would like to help take a look at the [list of issues](https://github.com/visulima/visulima/issues) and check our [Contributing](.github/CONTRIBUTING.md) guidelines.
+
+> **Note:** please note that this project is released with a Contributor Code of Conduct. By participating in this project you agree to abide by its terms.
+
+## Credits
+
+- [Daniel Bannert](https://github.com/prisis)
+- [All Contributors](https://github.com/visulima/visulima/graphs/contributors)
+
+## Made with ❤️ at Anolilab
+
+This is an open source project and will always remain free to use. If you think it's cool, please star it 🌟. [Anolilab](https://www.anolilab.com/open-source) is a Development and AI Studio. Contact us at [hello@anolilab.com](mailto:hello@anolilab.com) if you need any help with these technologies or just want to say hi!
+
+## License
+
+The visulima vis-mcp is open-sourced software licensed under the [MIT][license]
+
+<!-- badges -->
 
-**Maintained for OIDC setup purposes only**
+[license-badge]: https://img.shields.io/npm/l/@visulima/vis-mcp?style=for-the-badge
+[license]: https://github.com/visulima/visulima/blob/main/LICENSE
+[npm-downloads-badge]: https://img.shields.io/npm/dm/@visulima/vis-mcp?style=for-the-badge
+[npm-downloads]: https://www.npmjs.com/package/@visulima/vis-mcp
+[prs-welcome-badge]: https://img.shields.io/badge/PRs-welcome-brightgreen.svg?style=for-the-badge
+[prs-welcome]: https://github.com/visulima/visulima/blob/main/.github/CONTRIBUTING.md
+[chat-badge]: https://img.shields.io/discord/932323359193186354.svg?style=for-the-badge
+[chat]: https://discord.gg/TtFJY8xkFK
+[typescript-badge]: https://img.shields.io/badge/Typescript-294E80.svg?style=for-the-badge&logo=typescript
+[typescript-url]: https://www.typescriptlang.org/

package/dist/bin.js

@@ -0,0 +1,3 @@
+#!/usr/bin/env node
+import{startMcpServer as t}from"./packem_shared/registerAllTools-BOmyhKCR.js";try{await t()}catch(r){process.stderr.write(`[vis-mcp] failed to start: ${r instanceof Error?r.message:String(r)}
+`),process.exit(1)}

package/dist/index.d.ts

@@ -0,0 +1,109 @@
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+/**
+* Spawn a `vis` subprocess and capture stdout/stderr without piping to the
+* parent's stdio. The MCP server must keep its own stdout pristine — anything
+* other than JSON-RPC frames corrupts the protocol stream.
+*
+* `visBin` is the resolved path to the user's installed vis CLI; injected so
+* tests can point at a fixture instead of the real CLI.
+*/
+declare const execVis: (visBin: string, args: ReadonlyArray<string>, options?: ExecOptions) => Promise<ExecResult>;
+/**
+* Run `vis` and parse stdout as JSON. Throws when the subprocess fails or
+* stdout isn't valid JSON — callers map this into an `isError: true` MCP
+* response.
+*/
+declare const execVisJson: <T>(visBin: string, args: ReadonlyArray<string>, options?: ExecOptions) => Promise<T>;
+interface ExecResult {
+  exitCode: number;
+  stderr: string;
+  stdout: string;
+  timedOut: boolean;
+}
+interface ExecOptions {
+  cwd?: string;
+  env?: Record<string, string | undefined>;
+  /** Hard ceiling. The default 120s suits cache lookups and listings. */
+  timeoutMs?: number;
+}
+/**
+* MCP tool response shape used across all `vis` tools. Kept in one place so
+* adding a new tool doesn't require re-deriving the type from the SDK.
+*
+* The index signature matches the SDK's `CallToolResult` shape — the SDK
+* extends the JSON-RPC result with an open `_meta` bag and refuses anything
+* stricter at the assignment site.
+*/
+interface McpToolResponse {
+  [key: string]: unknown;
+  content: {
+    text: string;
+    type: "text";
+  }[];
+  isError?: boolean;
+}
+declare const okResponse: (payload: unknown) => McpToolResponse;
+declare const errorResponse: (error: unknown) => McpToolResponse;
+interface ToolContext {
+  /** Absolute path to the resolved `vis` CLI bundle. */
+  visBin: string;
+  /** Workspace root the MCP server should operate against. */
+  workspaceRoot: string;
+}
+/**
+* Dependencies a tool needs from the MCP SDK. Threaded through so each tool
+* stays a plain registration function and tests can swap in a fake `server`
+* without touching the real SDK.
+*/
+interface ToolDeps {
+  server: McpServer;
+}
+/**
+* Register every tool against an already-built MCP server. Pure wiring — no
+* I/O — so tests can drive it against an `InMemoryTransport` without forking
+* a subprocess.
+*/
+declare const registerAllTools: (deps: ToolDeps, context: ToolContext) => void;
+/**
+* Build a fully-configured MCP server with all vis tools registered. Returns
+* the server and deps so callers can connect any transport. Tests use this
+* with `InMemoryTransport.createLinkedPair()`.
+*/
+declare const createMcpServer: (context: ToolContext) => Promise<{
+  deps: ToolDeps;
+  server: McpServer;
+}>;
+/**
+* Boot the vis MCP server over stdio.
+*
+* Critical invariant: nothing in this process may write to stdout outside
+* the MCP transport. Any console.log in tool handlers will frame-corrupt
+* the JSON-RPC stream. Logs go to stderr only.
+*/
+declare const startMcpServer: () => Promise<void>;
+declare const registerCacheHash: ({
+  server
+}: ToolDeps, context: ToolContext) => void;
+declare const registerCacheWhy: ({
+  server
+}: ToolDeps, context: ToolContext) => void;
+declare const registerDescribeProject: ({
+  server
+}: ToolDeps, context: ToolContext) => void;
+declare const registerGetRunLogs: ({
+  server
+}: ToolDeps, context: ToolContext) => void;
+declare const registerListProjects: ({
+  server
+}: ToolDeps, context: ToolContext) => void;
+declare const registerListTargets: ({
+  server
+}: ToolDeps, context: ToolContext) => void;
+declare const isValidRunId: (value: string) => boolean;
+/**
+* Task IDs are `&lt;project>:&lt;target>`; both halves are package or npm-scope
+* shaped. The exec layer uses argv-form spawn so shell metacharacters are
+* inert, but a leading `-` would be parsed as a CLI flag by the vis CLI.
+*/
+declare const isValidTaskId: (value: string) => boolean;
+export { type ExecOptions, type ExecResult, type McpToolResponse, type ToolContext, type ToolDeps, createMcpServer, errorResponse, execVis, execVisJson, isValidRunId, isValidTaskId, okResponse, registerAllTools, registerCacheHash, registerCacheWhy, registerDescribeProject, registerGetRunLogs, registerListProjects, registerListTargets, startMcpServer };

package/dist/index.js

@@ -0,0 +1 @@
+import{execVis as o,execVisJson as s}from"./packem_shared/execVis-BzS_F-9x.js";import{errorResponse as i,okResponse as p}from"./packem_shared/okResponse-DdzqnveW.js";import{createMcpServer as c,registerAllTools as f,startMcpServer as m}from"./packem_shared/registerAllTools-BOmyhKCR.js";import{registerCacheHash as g}from"./packem_shared/registerCacheHash-CVckSIVO.js";import{registerCacheWhy as n}from"./packem_shared/registerCacheWhy-BfIjli7n.js";import{registerDescribeProject as h}from"./packem_shared/registerDescribeProject-Dhuzun-I.js";import{registerGetRunLogs as V}from"./packem_shared/registerGetRunLogs-BxkRfYZU.js";import{registerListProjects as T}from"./packem_shared/registerListProjects-C-AZj8RT.js";import{registerListTargets as k}from"./packem_shared/registerListTargets-Cq6bkF7O.js";import{isValidRunId as v,isValidTaskId as C}from"./packem_shared/isValidRunId-BKsKMWQf.js";export{c as createMcpServer,i as errorResponse,o as execVis,s as execVisJson,v as isValidRunId,C as isValidTaskId,p as okResponse,f as registerAllTools,g as registerCacheHash,n as registerCacheWhy,h as registerDescribeProject,V as registerGetRunLogs,T as registerListProjects,k as registerListTargets,m as startMcpServer};

package/dist/packem_shared/execVis-BzS_F-9x.js

@@ -0,0 +1,4 @@
+var x=Object.defineProperty;var m=(i,e)=>x(i,"name",{value:e,configurable:!0});import{spawn as v}from"node:child_process";var g=Object.defineProperty,w=m((i,e)=>g(i,"name",{value:e,configurable:!0}),"c");const l=12e4,O=w(async(i,e,n={})=>{const o=n.timeoutMs??l,t={cwd:n.cwd??process.cwd(),env:{...process.env,...n.env,NO_COLOR:"1"},stdio:["ignore","pipe","pipe"],windowsHide:!0};return await new Promise((p,f)=>{const r=v(process.execPath,[i,...e],t);let c="",d="",a=!1;const u=setTimeout(()=>{a=!0,r.kill("SIGTERM"),setTimeout(()=>r.kill("SIGKILL"),2e3).unref()},o);r.stdout?.setEncoding("utf8"),r.stdout?.on("data",s=>{c+=s}),r.stderr?.setEncoding("utf8"),r.stderr?.on("data",s=>{d+=s}),r.once("error",s=>{clearTimeout(u),f(s)}),r.once("close",s=>{clearTimeout(u),p({exitCode:s??-1,stderr:d,stdout:c,timedOut:a})})})},"execVis"),S=w(async(i,e,n={})=>{const o=await O(i,e,n);if(o.timedOut)throw new Error(`vis ${e.join(" ")} timed out after ${String(n.timeoutMs??l)}ms`);if(o.exitCode!==0){const t=o.stderr.trim().split(`
+`).slice(-5).join(`
+`);throw new Error(`vis ${e.join(" ")} exited with code ${String(o.exitCode)}${t?`
+${t}`:""}`)}try{return JSON.parse(o.stdout)}catch(t){throw new Error(`vis ${e.join(" ")} did not emit valid JSON: ${t instanceof Error?t.message:String(t)}`,{cause:t})}},"execVisJson");export{O as execVis,S as execVisJson};

package/dist/packem_shared/isValidRunId-BKsKMWQf.js

@@ -0,0 +1 @@
+var d=Object.defineProperty;var a=(i,s)=>d(i,"name",{value:s,configurable:!0});var t=Object.defineProperty,e=a((i,s)=>t(i,"name",{value:s,configurable:!0}),"s");const n=/^[\w.-]+$/,r=e(i=>n.test(i),"isValidRunId"),o=e(i=>i.length>0&&!i.startsWith("-")&&i.includes(":"),"isValidTaskId");export{r as isValidRunId,o as isValidTaskId};

package/dist/packem_shared/okResponse-DdzqnveW.js

@@ -0,0 +1 @@
+var o=Object.defineProperty;var t=(e,r)=>o(e,"name",{value:r,configurable:!0});var s=Object.defineProperty,n=t((e,r)=>s(e,"name",{value:r,configurable:!0}),"o");const p=n(e=>({content:[{text:typeof e=="string"?e:JSON.stringify(e),type:"text"}]}),"okResponse"),a=n(e=>{const r=e instanceof Error?e.message:String(e);return{content:[{text:JSON.stringify({error:r}),type:"text"}],isError:!0}},"errorResponse");export{a as errorResponse,p as okResponse};

package/dist/packem_shared/registerAllTools-BOmyhKCR.js

@@ -0,0 +1,3 @@
+var u=Object.defineProperty;var i=(e,r)=>u(e,"name",{value:r,configurable:!0});import{readFile as f}from"node:fs/promises";import{createRequire as g}from"node:module";import{resolve as c,dirname as p}from"node:path";import{pathToFileURL as w,fileURLToPath as h}from"node:url";import{McpServer as y}from"@modelcontextprotocol/sdk/server/mcp.js";import{StdioServerTransport as b}from"@modelcontextprotocol/sdk/server/stdio.js";import{findUp as S}from"@visulima/fs";import{registerCacheHash as k}from"./registerCacheHash-CVckSIVO.js";import{registerCacheWhy as T}from"./registerCacheWhy-BfIjli7n.js";import{registerDescribeProject as R}from"./registerDescribeProject-Dhuzun-I.js";import*as _ from"zod";import{execVisJson as m}from"./execVis-BzS_F-9x.js";import{okResponse as l,errorResponse as v}from"./okResponse-DdzqnveW.js";import{registerGetRunLogs as j}from"./registerGetRunLogs-BxkRfYZU.js";import{registerListProjects as I}from"./registerListProjects-C-AZj8RT.js";import{registerListTargets as P}from"./registerListTargets-Cq6bkF7O.js";var L=Object.defineProperty,O=i((e,r)=>L(e,"name",{value:r,configurable:!0}),"r");const C=O(({server:e},r)=>{e.registerTool("describe_template",{annotations:{readOnlyHint:!0},description:"Return full metadata for a scaffolding template: description, default destination, and the variable schema (name, type, default, required, prompt, enum values). Use this before suggesting a `vis generate` command so option values can be filled correctly.",inputSchema:{name:_.string().describe('Template name (e.g. "package", "component"). Use list_templates to see available names.')}},async({name:t})=>{try{const s=await m(r.visBin,["generate",t,"--describe","--json"],{cwd:r.workspaceRoot});return l(s)}catch(s){return v(s)}})},"registerDescribeTemplate");var M=Object.defineProperty,V=i((e,r)=>M(e,"name",{value:r,configurable:!0}),"n");const B=V(({server:e},r)=>{e.registerTool("list_templates",{annotations:{readOnlyHint:!0},description:"List scaffolding templates discovered in the workspace (`.vis/templates/`, `.moon/templates/`, and `vis.config.ts` `generator.templates`). Each entry includes name, source, on-disk path, and one-line description.",inputSchema:{}},async()=>{try{const t=await m(r.visBin,["generate","--list","--json"],{cwd:r.workspaceRoot});return l({count:t.length,templates:t})}catch(t){return v(t)}})},"registerListTemplates");var E=Object.defineProperty,o=i((e,r)=>E(e,"name",{value:r,configurable:!0}),"s");const U=o(e=>{const r=process.env.VIS_MCP_VIS_BIN;if(r)return c(r);const t=g(w(`${e}/package.json`));let s,a;try{s=t.resolve("@visulima/vis/package.json"),a=t("@visulima/vis/package.json")}catch(d){throw new Error(`Cannot resolve \`@visulima/vis\` from ${e}. Install it as a workspace dependency, or set VIS_MCP_VIS_BIN to a vis CLI path.`,{cause:d})}const n=typeof a.bin=="string"?a.bin:a.bin?.vis;if(!n)throw new Error("`@visulima/vis` is installed but does not declare a `vis` bin entry — install a current version.");return c(p(s),n)},"resolveVisBin"),$=o(async()=>{try{const e=await S("package.json",{cwd:p(h(import.meta.url))});return e?JSON.parse(await f(e,"utf8")).version??"0.0.0":"0.0.0"}catch(e){return process.stderr.write(`[vis-mcp] failed to read package.json: ${e instanceof Error?e.message:String(e)}
+`),"0.0.0"}},"loadVersion"),A=o((e,r)=>{I(e,r),R(e,r),P(e,r),B(e,r),C(e,r),j(e,r),T(e,r),k(e,r)},"registerAllTools"),D=o(async e=>{const r=new y({name:"vis",version:await $()}),t={server:r};return A(t,e),{deps:t,server:r}},"createMcpServer"),te=o(async()=>{const e=process.env.VIS_MCP_WORKSPACE_ROOT??process.cwd(),r={visBin:U(e),workspaceRoot:e},{server:t}=await D(r);await t.connect(new b),process.stderr.write(`[vis-mcp] ready (workspace: ${r.workspaceRoot})
+`)},"startMcpServer");export{D as createMcpServer,A as registerAllTools,te as startMcpServer};

package/dist/packem_shared/registerCacheHash-CVckSIVO.js

@@ -0,0 +1 @@
+var d=Object.defineProperty;var s=(e,r)=>d(e,"name",{value:r,configurable:!0});import*as o from"zod";import{execVisJson as p}from"./execVis-BzS_F-9x.js";import{errorResponse as n,okResponse as u}from"./okResponse-DdzqnveW.js";import{isValidTaskId as h,isValidRunId as l}from"./isValidRunId-BKsKMWQf.js";var m=Object.defineProperty,f=s((e,r)=>m(e,"name",{value:r,configurable:!0}),"n");const b=f(({server:e},r)=>{e.registerTool("cache_hash",{annotations:{readOnlyHint:!0},description:"Print the recorded hash and per-input hash details for a task — the contributing inputs (command, nodes, runtime, implicitDeps) that produced it.",inputSchema:{runId:o.string().optional().describe("Run ID to inspect (default: latest)"),taskId:o.string().describe('Task ID like "@my/app:build"')}},async({runId:t,taskId:i})=>{if(!h(i))return n(new Error(`Invalid taskId "${i}". Expected "<project>:<target>".`));if(t!==void 0&&!l(t))return n(new Error(`Invalid runId "${t}". Expected filesystem-safe slug ([A-Za-z0-9_.-]).`));try{const a=["cache","hash",i,"--format=json"];t&&a.push("--run",t);const c=await p(r.visBin,a,{cwd:r.workspaceRoot});return u(c)}catch(a){return n(a)}})},"registerCacheHash");export{b as registerCacheHash};

package/dist/packem_shared/registerCacheWhy-BfIjli7n.js

@@ -0,0 +1 @@
+var d=Object.defineProperty;var n=(r,e)=>d(r,"name",{value:e,configurable:!0});import*as o from"zod";import{execVisJson as p}from"./execVis-BzS_F-9x.js";import{errorResponse as i,okResponse as u}from"./okResponse-DdzqnveW.js";import{isValidTaskId as h,isValidRunId as l}from"./isValidRunId-BKsKMWQf.js";var m=Object.defineProperty,f=n((r,e)=>m(r,"name",{value:e,configurable:!0}),"i");const w=f(({server:r},e)=>{r.registerTool("cache_why",{annotations:{readOnlyHint:!0},description:"Explain why a task's cache hash rotated between runs. Diffs the task's hashDetails (command, nodes, runtime, implicitDeps) against the previous run to pinpoint what changed.",inputSchema:{runId:o.string().optional().describe("Run ID to inspect (default: latest)"),taskId:o.string().describe('Task ID like "@my/app:build"')}},async({runId:t,taskId:s})=>{if(!h(s))return i(new Error(`Invalid taskId "${s}". Expected "<project>:<target>".`));if(t!==void 0&&!l(t))return i(new Error(`Invalid runId "${t}". Expected filesystem-safe slug ([A-Za-z0-9_.-]).`));try{const a=["cache","why",s,"--format=json"];t&&a.push("--run",t);const c=await p(e.visBin,a,{cwd:e.workspaceRoot});return u(c)}catch(a){return i(a)}})},"registerCacheWhy");export{w as registerCacheWhy};

package/dist/packem_shared/registerDescribeProject-Dhuzun-I.js

@@ -0,0 +1 @@
+var i=Object.defineProperty;var a=(r,e)=>i(r,"name",{value:e,configurable:!0});import*as c from"zod";import{execVisJson as p}from"./execVis-BzS_F-9x.js";import{okResponse as l,errorResponse as s}from"./okResponse-DdzqnveW.js";var m=Object.defineProperty,g=a((r,e)=>m(r,"name",{value:e,configurable:!0}),"n");const b=g(({server:r},e)=>{r.registerTool("describe_project",{annotations:{readOnlyHint:!0},description:"Return full metadata for a single workspace project: language, layer, stack, type, tags, root path, and all targets.",inputSchema:{name:c.string().describe('Project name (e.g. "@visulima/cerebro")')}},async({name:o})=>{try{const t=(await p(e.visBin,["list","--json"],{cwd:e.workspaceRoot})).find(n=>n.name===o);return t?l(t):s(new Error(`No project named "${o}". Use list_projects to see available names.`))}catch(t){return s(t)}})},"registerDescribeProject");export{b as registerDescribeProject};

package/dist/packem_shared/registerGetRunLogs-BxkRfYZU.js

@@ -0,0 +1 @@
+var f=Object.defineProperty;var d=(t,r)=>f(t,"name",{value:r,configurable:!0});import{readFile as k}from"node:fs/promises";import{join as l}from"@visulima/path";import*as m from"zod";import{errorResponse as o,okResponse as p}from"./okResponse-DdzqnveW.js";import{isValidRunId as I}from"./isValidRunId-BKsKMWQf.js";var g=Object.defineProperty,y=d((t,r)=>g(t,"name",{value:r,configurable:!0}),"m");const h=y(({server:t},r)=>{t.registerTool("get_run_logs",{annotations:{readOnlyHint:!0},description:"Read a vis run summary from .task-runner/. Returns the most recent run by default, or a specific run when `runId` is set. Optionally filter to a single task with `taskId`.",inputSchema:{runId:m.string().optional().describe("Run ID (default: latest)"),taskId:m.string().optional().describe('Filter to a single task ID like "@my/app:build"')}},async({runId:e,taskId:a})=>{if(e!==void 0&&!I(e))return o(new Error(`Invalid runId "${e}". Expected filesystem-safe slug ([A-Za-z0-9_.-]).`));const i=e?l(r.workspaceRoot,".task-runner","runs",`${e}.json`):l(r.workspaceRoot,".task-runner","last-summary.json");try{const n=await k(i,"utf8"),s=JSON.parse(n);if(a){const u=s.tasks?.find(c=>c.taskId===a);return u?p({runId:s.runId,task:u}):o(new Error(`Task "${a}" not found in run "${s.runId??"(unknown)"}".`))}return p(s)}catch(n){return n.code==="ENOENT"?o(new Error(`No run summary at ${i}. Run a task first to populate it.`)):o(n)}})},"registerGetRunLogs");export{h as registerGetRunLogs};

package/dist/packem_shared/registerListProjects-C-AZj8RT.js

@@ -0,0 +1 @@
+var n=Object.defineProperty;var i=(t,e)=>n(t,"name",{value:e,configurable:!0});import*as a from"zod";import{execVisJson as c}from"./execVis-BzS_F-9x.js";import{okResponse as p,errorResponse as l}from"./okResponse-DdzqnveW.js";var g=Object.defineProperty,u=i((t,e)=>g(t,"name",{value:e,configurable:!0}),"n");const f=u(({server:t},e)=>{t.registerTool("list_projects",{annotations:{readOnlyHint:!0},description:'List all workspace projects with their language, type, layer, tags, and target metadata. Optionally filter with a vis query string (e.g. "tag=frontend", "type=application").',inputSchema:{query:a.string().optional().describe('Filter projects by vis query string (e.g. "tag=frontend")')}},async({query:s})=>{try{const r=["list","--json"];s&&r.push("--query",s);const o=await c(e.visBin,r,{cwd:e.workspaceRoot});return p({count:o.length,projects:o})}catch(r){return l(r)}})},"registerListProjects");export{f as registerListProjects};

package/dist/packem_shared/registerListTargets-Cq6bkF7O.js

@@ -0,0 +1 @@
+var l=Object.defineProperty;var c=(t,e)=>l(t,"name",{value:e,configurable:!0});import*as g from"zod";import{execVisJson as m}from"./execVis-BzS_F-9x.js";import{errorResponse as p,okResponse as j}from"./okResponse-DdzqnveW.js";var u=Object.defineProperty,d=c((t,e)=>u(t,"name",{value:e,configurable:!0}),"c");const v=d(({server:t},e)=>{t.registerTool("list_targets",{annotations:{readOnlyHint:!0},description:"List per-target rows across the workspace: which targets each project exposes, with type, command, and description. Optionally narrow to a single project.",inputSchema:{project:g.string().optional().describe('Limit to one project (e.g. "@visulima/cerebro")')}},async({project:r})=>{try{const o=await m(e.visBin,["list","--targets","--json"],{cwd:e.workspaceRoot}),a=r?o.filter(s=>s.name===r):o;if(r&&a.length===0)return p(new Error(`No project named "${r}". Use list_projects to see available names.`));const n=a.flatMap(s=>(s.targets??[]).map(i=>({project:s.name,target:i.name,...i})));return j({count:n.length,targets:n})}catch(o){return p(o)}})},"registerListTargets");export{v as registerListTargets};

package/package.json

@@ -1,10 +1,74 @@
 {
   "name": "@visulima/vis-mcp",
-  "version": "0.0.1",
-  "description": "OIDC trusted publishing setup package for @visulima/vis-mcp",
+  "version": "1.0.0-alpha.1",
+  "description": "MCP (Model Context Protocol) server for @visulima/vis — exposes vis tooling to AI agents over stdio",
   "keywords": [
-    "oidc",
-    "trusted-publishing",
-    "setup"
-  ]
-}
+    "agent",
+    "ai",
+    "claude",
+    "cursor",
+    "llm",
+    "mcp",
+    "model-context-protocol",
+    "vis",
+    "visulima"
+  ],
+  "homepage": "https://visulima.com/packages/vis-mcp",
+  "bugs": {
+    "url": "https://github.com/visulima/visulima/issues"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/visulima/visulima.git",
+    "directory": "packages/tooling/vis-mcp"
+  },
+  "funding": [
+    {
+      "type": "github",
+      "url": "https://github.com/sponsors/prisis"
+    },
+    {
+      "type": "consulting",
+      "url": "https://anolilab.com/support"
+    }
+  ],
+  "license": "MIT",
+  "author": {
+    "name": "Daniel Bannert",
+    "email": "d.bannert@anolilab.de"
+  },
+  "sideEffects": false,
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "bin": {
+    "vis-mcp": "./dist/bin.js"
+  },
+  "files": [
+    "dist/**",
+    "README.md",
+    "CHANGELOG.md",
+    "LICENSE.md"
+  ],
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.29.0",
+    "@visulima/fs": "5.0.0-alpha.13",
+    "@visulima/path": "3.0.0-alpha.10",
+    "zod": "4.4.3"
+  },
+  "peerDependencies": {
+    "@visulima/vis": "1.0.0-alpha.11"
+  },
+  "engines": {
+    "node": "^22.14.0 || >=24.10.0"
+  },
+  "publishConfig": {
+    "access": "public",
+    "provenance": true
+  }
+}