localwp-mcp 0.1.0 → 0.1.1

package/README.md

@@ -1,62 +1,21 @@
 # localwp-mcp
 
-`localwp-mcp` is an MCP server for LocalWP projects.
+`localwp-mcp` gives AI agents direct access to LocalWP sites through MCP.
 
-It discovers Local sites from Local's own metadata, resolves the correct Local PHP and MySQL runtimes for each site, and gives AI agents simple access to:
+It automatically finds your Local sites, uses the correct Local PHP and MySQL runtimes for each one, and lets an agent work with WordPress through WP-CLI, MySQL, logs, diagnostics, backups, and restore flows.
 
-- Local site discovery
-- Local logs and doctor-style diagnostics
-- site-aware WP-CLI
-- safe SQL reads
-- full SQL access when you opt into it
-- database export/import
-- Local-friendly backups
-- restore workflows
-- machine-readable Local diagnostics
-- MCP resources and prompts
+## What You Can Do
 
-## Project Docs
+- inspect Local sites and their runtime details
+- run WP-CLI against the correct site
+- query the WordPress database
+- allow full database writes when you want unrestricted local development
+- read recent logs and run site health checks
+- export, import, back up, and restore LocalWP sites
 
-- [Contributing](./CONTRIBUTING.md)
-- [Security Policy](./SECURITY.md)
-- [Release Checklist](./docs/RELEASE_CHECKLIST.md)
-- [Windows Test Handoff](./docs/WINDOWS_TEST_HANDOFF.md)
+## Install
 
-## Profiles
-
-The package now has only 2 profiles:
-
-- `safe`
-  Good default. Read-focused SQL plus safe WP-CLI inspection commands.
-- `full-access`
-  Best for local development when you want the agent to fully work on the site and database.
-
-`safe` is the default.
-
-## Tools
-
-- `list_local_sites`
-- `local_environment_check`
-- `local_doctor`
-- `local_logs`
-- `local_site_info`
-- `backup_site`
-- `db_export`
-- `db_import`
-- `restore_backup`
-- `mysql_query`
-  Safe profile SQL reads only.
-- `mysql_execute`
-  Full-access profile single-statement SQL execution.
-- `mysql_schema`
-  Accepts `table` and also `tableName` as a compatibility alias.
-- `execute_wp_cli`
-
-## Quick Setup
-
-### npm
-
-Once published, the simplest MCP config is:
+Use `npx` in your MCP client:
 
 ```json
 {
@@ -65,23 +24,20 @@ Once published, the simplest MCP config is:
       "command": "npx",
       "args": ["localwp-mcp"],
       "env": {
-        "LOCAL_SITE_NAME": "plovercrm",
-        "LOCALWP_MCP_PROFILE": "full-access"
+        "LOCALWP_MCP_PROFILE": "safe"
       }
     }
   }
 }
 ```
 
-If you want the cautious default instead, set:
+You can also install it globally:
 
-```json
-{
-  "LOCALWP_MCP_PROFILE": "safe"
-}
+```bash
+npm install -g localwp-mcp
 ```
 
-After a global install, you can also use:
+Then use:
 
 ```json
 {
@@ -96,134 +52,192 @@ After a global install, you can also use:
 }
 ```
 
-### From Source
-
-If you are running from a local clone:
+If you want the MCP to focus on one site by default, set:
 
-```bash
-pnpm install
-pnpm build
+```json
+{
+  "LOCAL_SITE_NAME": "example-site"
+}
 ```
 
-Then point your MCP client at the built entrypoint:
+## Access Modes
+
+`localwp-mcp` has 2 access modes:
+
+- `safe`
+  Best default for most people. Safe WordPress inspection commands, diagnostics, logs, database reads, and backup/export flows.
+- `full-access`
+  Best when you want the agent to fully work on your local site, including SQL writes, imports, and restore operations.
+
+`safe` is the default.
+
+To enable full local access:
 
 ```json
 {
-  "mcpServers": {
-    "localwp": {
-      "command": "node",
-      "args": [
-        "/Users/your-user/Projects/MCP-Servers/localwp-mcp/dist/index.js"
-      ],
-      "env": {
-        "LOCAL_SITE_NAME": "plovercrm",
-        "LOCALWP_MCP_PROFILE": "full-access"
-      }
-    }
-  }
+  "LOCALWP_MCP_PROFILE": "full-access"
 }
 ```
 
-## Recommended First Command
+## First Things To Try
+
+Start with:
+
+- `local_environment_check`
+- `local_doctor`
+- `list_local_sites`
+
+Those will tell you:
 
-Run `local_environment_check` or `local_doctor` first on any machine. They show:
+- which Local sites were discovered
+- whether the site is running
+- which Local runtimes were resolved
+- whether WP-CLI and MySQL are reachable
 
-- resolved Local metadata paths
-- resolved Local app-resource paths
-- WP-CLI/tooling resolution
-- optional WP-CLI and MySQL probes for a selected site
-- log availability and practical next steps
+## Common Workflows
 
-That makes support and cross-platform debugging much easier.
+### Inspect a Site
 
-## Backups and Database Transfers
+Use:
+
+- `local_site_info`
+- `local_doctor`
+- `local_logs`
+
+### Work With WordPress
+
+Use:
+
+- `execute_wp_cli`
+
+Examples:
+
+- list plugins
+- inspect options
+- list posts or users
+- run plugin-specific WP-CLI commands
+
+### Work With the Database
+
+Use:
+
+- `mysql_query`
+  Read-only SQL in `safe`
+- `mysql_execute`
+  Full SQL execution in `full-access`
+- `mysql_schema`
+  Table listing and table description helpers
+
+### Back Up or Restore a Site
+
+Use:
 
 - `backup_site`
-  Creates a backup folder for the selected site.
-- `backup_site` with `scope=database`
-  Creates a timestamped backup folder with a fresh SQL dump.
-- `backup_site` with `scope=full`
-  Copies the site's `app`, `conf`, and `logs` directories and writes a fresh SQL dump into `app/sql`.
 - `db_export`
-  Writes a SQL file directly. Good when you only want the database.
 - `db_import`
-  Imports either a `.sql` file or a `backup_site` directory. Requires `full-access`.
 - `restore_backup`
-  Restores from a `.sql` file or a `backup_site` directory. In `full-access`, it can also restore `app`, `conf`, and `logs` from a full backup.
 
-The full backup is intentionally folder-based instead of shelling out to platform-specific `zip` or `tar` commands. That keeps the MCP predictable across macOS, Windows, and Linux, and it stays close to Local's own site-folder restore shape.
+`backup_site` supports:
+
+- `database`
+- `full`
+
+The `full` backup format is folder-based and includes the site's `app`, `conf`, and `logs` directories plus a fresh SQL dump.
+
+## Built-In Capabilities
+
+### Tools
+
+- `list_local_sites`
+- `local_environment_check`
+- `local_doctor`
+- `local_logs`
+- `local_site_info`
+- `execute_wp_cli`
+- `mysql_query`
+- `mysql_execute`
+- `mysql_schema`
+- `db_export`
+- `db_import`
+- `backup_site`
+- `restore_backup`
+
+### MCP Resources
 
-## Resources and Prompts
+- `localwp://sites`
+- `localwp://sites/{siteName}/summary`
+- `localwp://sites/{siteName}/doctor`
+- `localwp://sites/{siteName}/logs`
 
-This MCP now also exposes lightweight resources and prompts:
+### MCP Prompts
 
-- Resource: `localwp://sites`
-  JSON catalog of discovered Local sites.
-- Resource template: `localwp://sites/{siteName}/summary`
-  Per-site Local resolution summary.
-- Resource template: `localwp://sites/{siteName}/doctor`
-  Per-site doctor output.
-- Resource template: `localwp://sites/{siteName}/logs`
-  Per-site recent logs.
-- Prompt: `diagnose_local_site`
-  Helps an agent diagnose a LocalWP site with the MCP tools.
-- Prompt: `restore_local_site`
-  Helps an agent restore a site from a SQL dump or backup directory.
+- `diagnose_local_site`
+- `restore_local_site`
 
-## Platform Compatibility
+## Platform Support
 
-- `macOS`
-  Uses Local metadata under `~/Library/Application Support/Local` and the standard Local app bundle resources.
-- `Windows`
-  Uses Local metadata under `%APPDATA%\\Local` and searches both per-user and `Program Files` installs for Local resources.
-- `Linux`
-  Uses Local metadata under `~/.config/Local` and the common `/opt/Local/resources/extraResources` install path.
+`localwp-mcp` is designed for:
 
-The resolver supports both current `lightning-services` layouts and older `site-binaries` layouts.
+- macOS
+- Windows
+- Linux
 
-## Configuration
+It supports both current Local `lightning-services` layouts and older `site-binaries` layouts.
 
-Optional environment variables:
+## Useful Environment Variables
+
+Most users only need these:
 
 - `LOCALWP_MCP_PROFILE`
-  `safe` or `full-access`
-- `LOCALWP_MCP_BACKUPS_DIR`
-  Optional shared backup directory. If omitted, backups are written under each Local site's `localwp-mcp-backups` folder.
 - `LOCAL_SITE_NAME`
 - `LOCAL_SITE_ID`
-- `LOCAL_APP_SUPPORT_DIR`
-- `LOCAL_EXTRA_RESOURCES_DIRS`
-- `LOCAL_RUN_DIR`
-- `LOCAL_LIGHTNING_SERVICES_DIR`
-- `LOCAL_LIGHTNING_SERVICES_DIRS`
-- `LOCAL_SITES_JSON`
-- `LOCAL_SITE_STATUSES_JSON`
-- `LOCAL_WP_CLI_PHAR`
-- `LOCAL_WP_CLI_CONFIG`
-- `LOCAL_HELPER_BIN_DIRS`
-- `LOCAL_MYSQL_HOST`
+- `LOCALWP_MCP_BACKUPS_DIR`
+
+Advanced override variables also exist for custom Local layouts, but most installations do not need them.
+
+## Troubleshooting
 
-## Why It Stays Simple
+If the MCP does not find your site or cannot run WP-CLI/MySQL:
 
-- plain TypeScript
-- `pnpm`
-- `tsc`
-- stdio transport
+1. Start the site in Local.
+2. Run `local_environment_check`.
+3. Run `local_doctor`.
+4. Check `local_logs`.
 
-There is no bundler here because this is a Node MCP server and the simpler build is easier to debug and maintain.
+Those tools are the fastest way to see whether the problem is:
 
-## Development
+- site selection
+- Local metadata resolution
+- WP-CLI resolution
+- MySQL connectivity
+- missing or stopped Local services
+
+## From Source
+
+If you are running from a local clone instead of npm:
 
 ```bash
 pnpm install
-pnpm check
-pnpm test
 pnpm build
-node dist/index.js
 ```
 
-For contribution and release workflows, see:
+Then point your MCP client at:
+
+```json
+{
+  "mcpServers": {
+    "localwp": {
+      "command": "node",
+      "args": ["/path/to/localwp-mcp/dist/index.js"]
+    }
+  }
+}
+```
+
+## For Contributors
+
+Contributor and maintainer docs live outside the main user guide:
 
 - [CONTRIBUTING.md](./CONTRIBUTING.md)
 - [SECURITY.md](./SECURITY.md)
-- [docs/RELEASE_CHECKLIST.md](./docs/RELEASE_CHECKLIST.md)
+- [Maintainer Docs](./docs/maintainers/README.md)

package/dist/prompts.js

@@ -7,7 +7,7 @@ export function registerPrompts(server) {
             siteName: z
                 .string()
                 .optional()
-                .describe("Optional Local site name, for example 'woo'."),
+                .describe("Optional Local site name, for example 'example-site'."),
         },
     }, async ({ siteName }) => {
         const target = siteName
@@ -36,7 +36,7 @@ export function registerPrompts(server) {
         argsSchema: {
             siteName: z
                 .string()
-                .describe("Local site name to restore, for example 'woo'."),
+                .describe("Local site name to restore, for example 'example-site'."),
             sourcePath: z
                 .string()
                 .describe("Path to the .sql file or backup_site directory to restore."),

package/dist/prompts.js.map

@@ -1 +1 @@
-{"version":3,"file":"prompts.js","sourceRoot":"","sources":["../src/prompts.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB,MAAM,UAAU,eAAe,CAAC,MAAiB;IAC/C,MAAM,CAAC,cAAc,CACnB,qBAAqB,EACrB;QACE,KAAK,EAAE,qBAAqB;QAC5B,WAAW,EACT,0GAA0G;QAC5G,UAAU,EAAE;YACV,QAAQ,EAAE,CAAC;iBACR,MAAM,EAAE;iBACR,QAAQ,EAAE;iBACV,QAAQ,CAAC,8CAA8C,CAAC;SAC5D;KACF,EACD,KAAK,EAAE,EAAE,QAAQ,EAAE,EAAE,EAAE;QACrB,MAAM,MAAM,GAAG,QAAQ;YACrB,CAAC,CAAC,mBAAmB,QAAQ,GAAG;YAChC,CAAC,CAAC,yBAAyB,CAAC;QAE9B,OAAO;YACL,QAAQ,EAAE;gBACR;oBACE,IAAI,EAAE,MAAM;oBACZ,OAAO,EAAE;wBACP,IAAI,EAAE,MAAM;wBACZ,IAAI,EAAE;4BACJ,YAAY,MAAM,qBAAqB;4BACvC,sDAAsD;4BACtD,qHAAqH;4BACrH,6EAA6E;yBAC9E,CAAC,IAAI,CAAC,GAAG,CAAC;qBACZ;iBACF;aACF;SACF,CAAC;IACJ,CAAC,CACF,CAAC;IAEF,MAAM,CAAC,cAAc,CACnB,oBAAoB,EACpB;QACE,KAAK,EAAE,oBAAoB;QAC3B,WAAW,EACT,iGAAiG;QACnG,UAAU,EAAE;YACV,QAAQ,EAAE,CAAC;iBACR,MAAM,EAAE;iBACR,QAAQ,CAAC,gDAAgD,CAAC;YAC7D,UAAU,EAAE,CAAC;iBACV,MAAM,EAAE;iBACR,QAAQ,CAAC,4DAA4D,CAAC;SAC1E;KACF,EACD,KAAK,EAAE,EAAE,QAAQ,EAAE,UAAU,EAAE,EAAE,EAAE;QACjC,OAAO;YACL,QAAQ,EAAE;gBACR;oBACE,IAAI,EAAE,MAAM;oBACZ,OAAO,EAAE;wBACP,IAAI,EAAE,MAAM;wBACZ,IAAI,EAAE;4BACJ,2BAA2B,QAAQ,WAAW,UAAU,IAAI;4BAC5D,gFAAgF;4BAChF,4DAA4D;4BAC5D,6GAA6G;4BAC7G,+FAA+F;yBAChG,CAAC,IAAI,CAAC,GAAG,CAAC;qBACZ;iBACF;aACF;SACF,CAAC;IACJ,CAAC,CACF,CAAC;AACJ,CAAC"}
+{"version":3,"file":"prompts.js","sourceRoot":"","sources":["../src/prompts.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB,MAAM,UAAU,eAAe,CAAC,MAAiB;IAC/C,MAAM,CAAC,cAAc,CACnB,qBAAqB,EACrB;QACE,KAAK,EAAE,qBAAqB;QAC5B,WAAW,EACT,0GAA0G;QAC5G,UAAU,EAAE;YACV,QAAQ,EAAE,CAAC;iBACR,MAAM,EAAE;iBACR,QAAQ,EAAE;iBACV,QAAQ,CAAC,uDAAuD,CAAC;SACrE;KACF,EACD,KAAK,EAAE,EAAE,QAAQ,EAAE,EAAE,EAAE;QACrB,MAAM,MAAM,GAAG,QAAQ;YACrB,CAAC,CAAC,mBAAmB,QAAQ,GAAG;YAChC,CAAC,CAAC,yBAAyB,CAAC;QAE9B,OAAO;YACL,QAAQ,EAAE;gBACR;oBACE,IAAI,EAAE,MAAM;oBACZ,OAAO,EAAE;wBACP,IAAI,EAAE,MAAM;wBACZ,IAAI,EAAE;4BACJ,YAAY,MAAM,qBAAqB;4BACvC,sDAAsD;4BACtD,qHAAqH;4BACrH,6EAA6E;yBAC9E,CAAC,IAAI,CAAC,GAAG,CAAC;qBACZ;iBACF;aACF;SACF,CAAC;IACJ,CAAC,CACF,CAAC;IAEF,MAAM,CAAC,cAAc,CACnB,oBAAoB,EACpB;QACE,KAAK,EAAE,oBAAoB;QAC3B,WAAW,EACT,iGAAiG;QACnG,UAAU,EAAE;YACV,QAAQ,EAAE,CAAC;iBACR,MAAM,EAAE;iBACR,QAAQ,CAAC,yDAAyD,CAAC;YACtE,UAAU,EAAE,CAAC;iBACV,MAAM,EAAE;iBACR,QAAQ,CAAC,4DAA4D,CAAC;SAC1E;KACF,EACD,KAAK,EAAE,EAAE,QAAQ,EAAE,UAAU,EAAE,EAAE,EAAE;QACjC,OAAO;YACL,QAAQ,EAAE;gBACR;oBACE,IAAI,EAAE,MAAM;oBACZ,OAAO,EAAE;wBACP,IAAI,EAAE,MAAM;wBACZ,IAAI,EAAE;4BACJ,2BAA2B,QAAQ,WAAW,UAAU,IAAI;4BAC5D,gFAAgF;4BAChF,4DAA4D;4BAC5D,6GAA6G;4BAC7G,+FAA+F;yBAChG,CAAC,IAAI,CAAC,GAAG,CAAC;qBACZ;iBACF;aACF;SACF,CAAC;IACJ,CAAC,CACF,CAAC;AACJ,CAAC"}

package/dist/tool-schemas.js

@@ -7,7 +7,7 @@ export const siteSelectorSchema = {
     siteName: z
         .string()
         .optional()
-        .describe("Optional Local site name, for example 'plovercrm'."),
+        .describe("Optional Local site name, for example 'example-site'."),
 };
 export const logScopeSchema = z
     .enum(["site", "global", "all"])

package/dist/tool-schemas.js.map

@@ -1 +1 @@
-{"version":3,"file":"tool-schemas.js","sourceRoot":"","sources":["../src/tool-schemas.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB,MAAM,CAAC,MAAM,kBAAkB,GAAG;IAChC,MAAM,EAAE,CAAC;SACN,MAAM,EAAE;SACR,QAAQ,EAAE;SACV,QAAQ,CAAC,kDAAkD,CAAC;IAC/D,QAAQ,EAAE,CAAC;SACR,MAAM,EAAE;SACR,QAAQ,EAAE;SACV,QAAQ,CAAC,oDAAoD,CAAC;CAClE,CAAC;AAEF,MAAM,CAAC,MAAM,cAAc,GAAG,CAAC;KAC5B,IAAI,CAAC,CAAC,MAAM,EAAE,QAAQ,EAAE,KAAK,CAAC,CAAC;KAC/B,QAAQ,EAAE;KACV,QAAQ,CACP,0EAA0E,CAC3E,CAAC;AAEJ,MAAM,CAAC,MAAM,iBAAiB,GAAG,CAAC;KAC/B,IAAI,CAAC,CAAC,UAAU,EAAE,MAAM,CAAC,CAAC;KAC1B,QAAQ,EAAE;KACV,QAAQ,CACP,6GAA6G,CAC9G,CAAC"}
+{"version":3,"file":"tool-schemas.js","sourceRoot":"","sources":["../src/tool-schemas.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB,MAAM,CAAC,MAAM,kBAAkB,GAAG;IAChC,MAAM,EAAE,CAAC;SACN,MAAM,EAAE;SACR,QAAQ,EAAE;SACV,QAAQ,CAAC,kDAAkD,CAAC;IAC/D,QAAQ,EAAE,CAAC;SACR,MAAM,EAAE;SACR,QAAQ,EAAE;SACV,QAAQ,CAAC,uDAAuD,CAAC;CACrE,CAAC;AAEF,MAAM,CAAC,MAAM,cAAc,GAAG,CAAC;KAC5B,IAAI,CAAC,CAAC,MAAM,EAAE,QAAQ,EAAE,KAAK,CAAC,CAAC;KAC/B,QAAQ,EAAE;KACV,QAAQ,CACP,0EAA0E,CAC3E,CAAC;AAEJ,MAAM,CAAC,MAAM,iBAAiB,GAAG,CAAC;KAC/B,IAAI,CAAC,CAAC,UAAU,EAAE,MAAM,CAAC,CAAC;KAC1B,QAAQ,EAAE;KACV,QAAQ,CACP,6GAA6G,CAC9G,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "localwp-mcp",
-  "version": "0.1.0",
+  "version": "0.1.1",
   "description": "A LocalWP-aware MCP server for WordPress developers with simple safe and full-access profiles, logs, doctor diagnostics, SQL access, backups, restore flows, MCP resources/prompts, and site-aware WP-CLI.",
   "type": "module",
   "packageManager": "pnpm@10.32.1",