@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"

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
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
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