Local development

Prerequisites: Node.js 18 or higher. Check your version with node --version.

Repository structure

HolyStitch is a monorepo managed with npm workspaces. The MCP server — the only published package — lives under packages/mcp-server/.

holystitch/
├── package.json                  ← workspace root (build / dev / lint scripts)
└── packages/
    └── mcp-server/
        ├── package.json          ← @stitch-to-react/mcp-server
        ├── tsconfig.json
        ├── src/
        │   ├── index.ts          ← MCP server entry point
        │   └── pipeline/
        │       ├── compiler.ts   ← HTML → JSX transformer
        │       ├── parser.ts     ← Stitch HTML parser
        │       └── ...
        └── dist/                 ← compiled output (after npm run build)

The root package.json delegates to workspaces — you always run scripts from the repo root.

Clone and install

Clone the repository

git clone https://github.com/BaselAshraf81/holystitch
cd holystitch

Install dependencies

npm install

This installs dependencies for all workspaces in one pass.

Build the project

npm run build

This runs tsc inside packages/mcp-server/, compiling TypeScript to packages/mcp-server/dist/. The entry point is dist/index.js.

You must run npm run build before pointing any MCP host at the local repo. The MCP host executes the compiled JavaScript in dist/, not the TypeScript source.

Available scripts

All scripts are run from the repo root.

Script	What it does
`npm run build`	Compiles all workspaces (`tsc` in `packages/mcp-server/`)
`npm run dev`	Runs `tsc --watch` in `packages/mcp-server/` — recompiles on every save
`npm run lint`	Runs `tsc --noEmit` across all workspaces — type-checks without emitting files

TypeScript build process

The mcp-server package uses a standard tsc compile step with no bundler. The tsconfig.json in packages/mcp-server/ targets ESM output ("type": "module" in its package.json). Running npm run build from the root triggers npm run build --workspaces, which resolves to tsc in each workspace.

# Equivalent to what `npm run build` does inside packages/mcp-server/
cd packages/mcp-server
npx tsc

After a successful build, dist/index.js is the executable entry point.

Testing changes against a real MCP host

After making and building changes, point your MCP host at the local dist/index.js instead of a published package.

Make your changes

Edit files under packages/mcp-server/src/.

Rebuild

npm run build

Or leave npm run dev running in a terminal — it recompiles automatically on every save.

Configure your MCP host to use the local build

Update your MCP host config to point at the local dist/index.js. Replace /path/to/holystitch with the actual path where you cloned the repo.

{
  "mcpServers": {
    "holystitch": {
      "command": "node",
      "args": ["/path/to/holystitch/packages/mcp-server/dist/index.js"],
      "env": {
        "STITCH_API_KEY": "your-api-key-here"
      }
    }
  }
}

{
  "mcpServers": {
    "holystitch": {
      "command": "node",
      "args": ["/path/to/holystitch/packages/mcp-server/dist/index.js"],
      "env": {
        "STITCH_API_KEY": "your-api-key-here"
      }
    }
  }
}

On Windows, use forward slashes or escaped backslashes in the path: "C:/Users/alice/holystitch/packages/mcp-server/dist/index.js"

Restart your MCP host

Most MCP hosts load the server process at startup. Restart the IDE or reload the MCP server to pick up the updated binary.

Run a conversion

Trigger the convert_stitch_to_react tool with a real Stitch project ID and verify the output matches your expectations.

Type-checking without building

To catch type errors quickly without emitting any files:

npm run lint

This runs tsc --noEmit across all workspaces and exits non-zero if there are any errors. Run this before opening a PR.

Get Started

Configuration

How It Works

Output

Contributing

Repository structure

Clone and install

Available scripts

TypeScript build process

Testing changes against a real MCP host

Type-checking without building

​Repository structure

​Clone and install

​Available scripts

​TypeScript build process

​Testing changes against a real MCP host

​Type-checking without building

Repository structure

Clone and install

Available scripts

TypeScript build process

Testing changes against a real MCP host

Type-checking without building