npm package discovery and stats viewer.

Discover Tips

  • General search

    [free text search, go nuts!]

  • Package details

    pkg:[package-name]

  • User packages

    @[username]

Sponsor

Optimize Toolset

I’ve always been into building performant and accessible sites, but lately I’ve been taking it extremely seriously. So much so that I’ve been building a tool to help me optimize and monitor the sites that I build to make sure that I’m making an attempt to offer the best experience to those who visit them. If you’re into performant, accessible and SEO friendly sites, you might like it too! You can check it out at Optimize Toolset.

About

Hi, 👋, I’m Ryan Hefner  and I built this site for me, and you! The goal of this site was to provide an easy way for me to check the stats on my npm packages, both for prioritizing issues and updates, and to give me a little kick in the pants to keep up on stuff.

As I was building it, I realized that I was actually using the tool to build the tool, and figured I might as well put this out there and hopefully others will find it to be a fast and useful way to search and browse npm packages as I have.

If you’re interested in other things I’m working on, follow me on Twitter or check out the open source projects I’ve been publishing on GitHub.

I am also working on a Twitter bot for this site to tweet the most popular, newest, random packages from npm. Please follow that account now and it will start sending out packages soon–ish.

Open Software & Tools

This site wouldn’t be possible without the immense generosity and tireless efforts from the people who make contributions to the world and share their work via open source initiatives. Thank you 🙏

© 2026 – Pkg Stats / Ryan Hefner

@permitplane/mcp

v0.1.0

Published

MCP server that lets AI assistants operate PermitPlane through the management API (/manage/v1).

Readme

@permitplane/mcp

MCP server that lets AI assistants (Claude, Cursor, Codex) operate PermitPlane through the management API (/manage/v1). It is a thin translator: which tools exist, their schemas, descriptions, prompts and server instructions all come from the PermitPlane server you point it at (GET /manage/v1/agent/tools), so the tools always match that server's version. It runs over stdio.

Install

npx -y @permitplane/[email protected]

Licensed under Apache-2.0. Homepage: https://permitplane.com

Requirements

Node.js 22 or newer.

Configuration

| Setting | Environment variable | Config file field | Notes | | --- | --- | --- | --- | | API key | PERMITPLANE_API_KEY | api_key | Optional. Without a key only public tools (docs, agent signup) are available. | | Base URL | PERMITPLANE_BASE_URL | base_url | Required. https:// only, except http://localhost, 127.0.0.1, [::1]. No default origin. | | Config file path | PERMITPLANE_CONFIG | - | Overrides the default path below. |

Precedence: the environment variable, then the config file.

Default config file: %APPDATA%\PermitPlane\mcp.json on Windows, $XDG_CONFIG_HOME/permitplane/mcp.json or ~/.config/permitplane/mcp.json elsewhere. Format:

{ "base_url": "https://<your PermitPlane origin>", "api_key": "ppk_test_..." }

On macOS and Linux run chmod 600 on the file; the server warns on stderr when it is readable by others. No tool takes an API key as an argument, and the key is never logged.

Public mode and signup

Without a key the assistant can read the public docs and start an agent signup. A human confirms by email. When the signup completes, the server saves the new key to the config file (only when no key was configured), switches to the full tool set and tells the client the tool list changed. The key is not shown in the conversation. If your client does not refresh its tools, restart the server.

Client setup

Recommended: keep the key and base URL in the PermitPlane config file, so client configs hold no secret.

Claude Desktop, claude_desktop_config.json (Windows %APPDATA%\Claude\, macOS ~/Library/Application Support/Claude/):

{
  "mcpServers": {
    "permitplane": {
      "command": "npx",
      "args": ["-y", "@permitplane/[email protected]"]
    }
  }
}

Alternative with environment variables (the key then sits in this local file):

{
  "mcpServers": {
    "permitplane": {
      "command": "npx",
      "args": ["-y", "@permitplane/[email protected]"],
      "env": { "PERMITPLANE_BASE_URL": "https://<your PermitPlane origin>", "PERMITPLANE_API_KEY": "ppk_test_..." }
    }
  }
}

Claude Code (user scope; the key stays in the PermitPlane config file):

claude mcp add --scope user --transport stdio permitplane -- npx -y @permitplane/[email protected]

Shared project config .mcp.json (commit it; each developer's key comes from their own environment through ${VAR} expansion, never from the repository):

{
  "mcpServers": {
    "permitplane": {
      "command": "npx",
      "args": ["-y", "@permitplane/[email protected]"],
      "env": { "PERMITPLANE_BASE_URL": "https://<your PermitPlane origin>", "PERMITPLANE_API_KEY": "${PERMITPLANE_API_KEY}" }
    }
  }
}

Cursor, ~/.cursor/mcp.json (global) or .cursor/mcp.json (project): same mcpServers shape as Claude Desktop.

Codex, ~/.codex/config.toml:

[mcp_servers.permitplane]
command = "npx"
args = ["-y", "@permitplane/[email protected]"]

Behaviour

| Server answer | What the assistant sees | | --- | --- | | 2xx JSON | The JSON, labelled as data; a "store now" note when a secret field is present (shown once). | | 2xx other (CSV, Markdown, ...) | The raw text, cut at 100 000 characters. | | 200 preview (dry_run=true) | "Preview only", the effects, whether approval is needed. The preview token is kept by the server process. | | 202 approval_required | Success, not an error: the console link a human owner opens, the request id, the expiry. | | 4xx | Error with code, hint, docs slug (permitplane://docs/<slug>), field errors and request_id. 401 points at the config file. | | 429, 502, 503, 504, connection failure | Up to 2 retries when safe (GET, or a mutation with an Idempotency-Key), then an error. | | Redirects | Refused. |

Every mutation carries an Idempotency-Key. A destructive tool is refused locally until the same call was previewed with dry_run=true in this session (10 minutes). The preview token is then sent with the real call.

Security notes

  • The key is never a tool argument, never logged, never written to stdout. stdout carries JSON-RPC only.
  • The base URL must be https (loopback excepted). Tool paths from the server must start with a single / and are always prefixed with the base URL; redirects are refused.
  • Tool results are labelled as data from PermitPlane, not instructions.
  • Runtime dependency: one package, @modelcontextprotocol/server, pinned exactly; npm-shrinkwrap.json pins the rest.

Troubleshooting

  • 401: the key expired, was revoked or belongs to another server. Create a new key in the console and put it in the config file.
  • Tools did not refresh after signup: restart the PermitPlane MCP server in your client.
  • Windows, the client cannot start npx: use "command": "cmd", "args": ["/c", "npx", "-y", "@permitplane/[email protected]"].