@jspm/local-mcp

A local-first Model Context Protocol server for managing JSPM import maps inside a real project directory. Uses @jspm/generator to keep the full import map correct instead of hand-editing only the imports section.

Built for coding agents with filesystem access to your repo (Codex, Claude Code / Claude Desktop, Cursor, VS Code MCP).

Tools

Read-only

| Tool | Description | Inputs | |------|-------------|--------| | get_status | Returns the active project path, map target, environment conditions, and generator options. | none | | get_importmap | Returns the current import map as JSON with the list of installed top-level specifiers. Requires set_project first. | none |

Project setup

| Tool | Description | Inputs | |------|-------------|--------| | set_project | Sets the active project directory. | path: string | | set_target | Choose importmap file or HTML injection mode. | target: string, fileName?: string, esModuleShims?: boolean | | set_env | Switch between "production" and "development". | environment: "production"|"development", customConditions?: string[] |

Generator configuration

| Tool | Description | Inputs | |------|-------------|--------| | set_generator_options | Configure CommonJS, TypeScript, SystemJS, integrity, fetch retries, default provider, and more. | commonJS?, typeScript?, system?, integrity?, fetchRetries?, defaultProvider?, cache?, providers?, resolutions?, ignore?, reinstall? | | set_provider | Set default provider (e.g. "jspm.io", "jsdelivr", "unpkg") and scoped overrides. | defaultProvider?, overrides?, reinstall? | | remove_provider_override | Remove one or more scoped provider overrides. | specifiers: string[], reinstall? | | set_cache | Configure cache mode (true, false, or "offline"). | cache: boolean|"offline", reinstall? | | set_resolution | Add or update package resolution overrides. | resolutions: {specifier, target}[], reinstall? | | remove_resolution | Remove package resolution overrides. | specifiers: string[], reinstall? | | set_ignore | Replace the list of specifiers JSPM ignores during tracing. | specifiers: string[], reinstall? |

Package management

| Tool | Description | Inputs | |------|-------------|--------| | install_package | Install one or more packages via the configured provider. | packages: {packageName, version?}[] | | uninstall_package | Remove one or more packages from the import map. | packageName: string|string[] | | trace_file | Trace imports from local source files and add required mappings. | fileNames: string[] |

Typical Flow

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"] })

Install

npx -y @jspm/local-mcp

Or globally:

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

MCP Client Setup

All clients use the same pattern:

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

For VS Code / GitHub Copilot, use the "servers" key instead of "mcpServers".

If npx is unavailable, point directly to the installed executable:

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

Local Development

npm install
npm run build
npm start

For auto-reload during development:

• Terminal: npm run dev (watches src/ and rebuilds dist/ on save)
• MCP client config: node --watch /path/to/jspm-mcp/dist/cli.js

The --watch flag restarts the server automatically when dist/ changes.

Publish

npm run build
npm publish --access public

prepublishOnly rebuilds dist before publish.

License

MIT