@jspm/local-mcp

@jspm/local-mcp is a local-first Model Context Protocol server for managing JSPM import maps inside a real project directory.

It is built for coding agents that already have filesystem access to your repo, such as Codex, Claude Code / Claude Desktop, Cursor, and VS Code MCP clients.

Instead of asking an LLM to hand-edit only the imports section and accidentally break scopes, this server uses @jspm/generator to keep the full import map correct.

Why local-first

• It works directly against your project files.
• It can write either importmap.json or inject an inline import map into an HTML file.
• It can trace local source files and install the dependencies they actually use.
• It preserves and reloads an existing import map when you revisit a project.

Tools

The server exposes these MCP tools:

• set_project: set the working project directory.
• set_target: choose importmap or html output mode.
• install_package: install one or more packages with JSPM.
• uninstall_package: remove one or more packages from the import map.
• trace_file: trace imports from local source files and add the required mappings.

Install

After publish, the simplest way to run it will be with npx:

npx -y @jspm/local-mcp

You can also install it globally:

npm install -g @jspm/local-mcp
jspm-local-mcp

MCP Client Setup

Codex

Add an MCP server that runs npx:

{
  "mcpServers": {
    "jspm": {
      "command": "npx",
      "args": ["-y", "@jspm/local-mcp"]
    }
  }
}

Claude Desktop

{
  "mcpServers": {
    "jspm": {
      "command": "npx",
      "args": ["-y", "@jspm/local-mcp"]
    }
  }
}

VS Code MCP / GitHub Copilot

{
  "servers": {
    "jspm": {
      "command": "npx",
      "args": ["-y", "@jspm/local-mcp"]
    }
  }
}

If your environment does not expose npx, point the client at the installed executable instead.

Typical Flow

Example conversation:

Set the project to the current workspace.
Use index.html as the import map target.
Install react and react-dom.
Trace src/main.js and update the import map.

Equivalent tool calls:

1. set_project({ path: "/absolute/path/to/project" })
2. set_target({ target: "html", fileName: "index.html" })
3. install_package({ packages: [{ packageName: "react" }, { packageName: "react-dom" }] })
4. trace_file({ fileNames: ["src/main.js"] })

Behavior Notes

• set_project defaults to importmap.json.
• Switching targets reloads the generator from the current file state.
• set_target("html") reads the existing HTML file and preserves any inline import map already there.
• trace_file works on files inside the configured project directory.
• Target files are restricted to the configured project directory.

Local Development

npm install
npm run build
npm start

For local unpublished testing, point your MCP client to:

{
  "command": "node",
  "args": ["/absolute/path/to/jspm-mcp/dist/index.js"]
}

Publish Checklist

npm run build
npm publish --access public

prepublishOnly rebuilds dist before publish.

License

MIT