@mjquinlan2000/practicepanther-mcp 0.1.2 → 0.1.4

package/README.md

@@ -1,42 +1,42 @@
 # @mjquinlan2000/practicepanther-mcp
 
-MCP server for the [PracticePanther](https://www.practicepanther.com/) legal practice management API. Exposes PracticePanther's REST API as MCP tools so AI assistants (Claude Desktop, etc.) can read data from PracticePanther accounts.
+MCP server for the [PracticePanther](https://www.practicepanther.com/) legal practice management API. Exposes PracticePanther's REST API as read-only MCP tools so AI assistants (Claude Desktop, etc.) can read data from PracticePanther accounts.
 
-## Installation
+## Quick Start
 
 ```sh
-npm install @mjquinlan2000/practicepanther-mcp
-# or run directly
-npx @mjquinlan2000/practicepanther-mcp
+PP_ACCESS_TOKEN=your_token npx @mjquinlan2000/practicepanther-mcp
 ```
 
-## Setup
+## Authentication
 
-### 1. Obtain API credentials
+### Option 1: Access token (simplest)
 
-Register an OAuth2 application in PracticePanther to get a client ID and secret.
+If you already have a PracticePanther access token, set it as an environment variable:
 
-### 2. Set environment variables
+```sh
+export PP_ACCESS_TOKEN=your_token
+```
+
+### Option 2: OAuth flow
+
+If you have OAuth2 client credentials, you can use the built-in auth CLI to obtain tokens:
 
 ```sh
 export PP_CLIENT_ID=your_client_id
 export PP_CLIENT_SECRET=your_client_secret
 export PP_REDIRECT_URI=http://127.0.0.1:8080/callback
-```
-
-### 3. Authenticate
 
-```sh
-# Initial OAuth2 authorization (opens browser)
-yarn auth
+# Opens a browser for OAuth2 authorization
+npx @mjquinlan2000/practicepanther-mcp auth
 
 # Refresh an expired token
-yarn auth:refresh
+npx @mjquinlan2000/practicepanther-mcp auth refresh
 ```
 
-Tokens are persisted to `~/.config/practicepanther-mcp/tokens.json` and auto-refresh when the server runs.
+Tokens are saved to `~/.config/practicepanther-mcp/tokens.json`.
 
-Alternatively, set `PP_ACCESS_TOKEN` directly to skip the OAuth flow.
+PracticePanther supports refresh tokens — if `PP_CLIENT_ID` and `PP_CLIENT_SECRET` are set at runtime, the server will auto-refresh expired tokens.
 
 ## MCP Client Configuration
 
@@ -49,25 +49,24 @@ Add to your MCP client config (e.g. Claude Desktop `claude_desktop_config.json`)
       "command": "npx",
       "args": ["@mjquinlan2000/practicepanther-mcp"],
       "env": {
-        "PP_CLIENT_ID": "your_client_id",
-        "PP_CLIENT_SECRET": "your_client_secret"
+        "PP_ACCESS_TOKEN": "your_token"
       }
     }
   }
 }
 ```
 
-For local development with `tsx`:
+To use OAuth with auto-refresh instead, pass the client credentials:
 
 ```json
 {
   "mcpServers": {
     "practicepanther": {
-      "command": "tsx",
-      "args": ["src/server.ts"],
+      "command": "npx",
+      "args": ["@mjquinlan2000/practicepanther-mcp"],
       "env": {
-        "PP_CLIENT_ID": "${PP_CLIENT_ID}",
-        "PP_CLIENT_SECRET": "${PP_CLIENT_SECRET}"
+        "PP_CLIENT_ID": "your_client_id",
+        "PP_CLIENT_SECRET": "your_client_secret"
       }
     }
   }
@@ -76,7 +75,7 @@ For local development with `tsx`:
 
 ## Available Tools
 
-The server registers tools for the following PracticePanther entities. Each entity has a `get_<entity>` (by ID) and `list_<entities>` tool unless noted otherwise.
+The server registers read-only tools for the following PracticePanther entities. Each entity has a `get_<entity>` (by ID) and `list_<entities>` tool unless noted otherwise.
 
 | Entity | Tools |
 |--------|-------|
@@ -103,28 +102,52 @@ The server registers tools for the following PracticePanther entities. Each enti
 | Time Entries | `get_time_entry`, `list_time_entries` |
 | Users | `get_me`, `get_user`, `list_users` |
 
-## Development
+## Local Development
 
 ```sh
-yarn start          # Run server locally (stdio transport)
-yarn build          # Bundle with tsup
-yarn typecheck      # Type-check with tsc --noEmit
-yarn spec:generate  # Fetch Swagger spec, convert to OpenAPI 3, regenerate typed client
+git clone https://github.com/mjquinlan2000/node-mcps.git
+cd node-mcps
+yarn install
+yarn build
+
+# Run the server locally
+yarn workspace @mjquinlan2000/practicepanther-mcp start
+
+# Run tests
+yarn workspace @mjquinlan2000/practicepanther-mcp test
+yarn workspace @mjquinlan2000/practicepanther-mcp test:watch
+
+# Regenerate typed client from API spec
+yarn workspace @mjquinlan2000/practicepanther-mcp spec:generate
+```
+
+For local dev with an MCP client, use `tsx` directly:
+
+```json
+{
+  "mcpServers": {
+    "practicepanther": {
+      "command": "tsx",
+      "args": ["/path/to/node-mcps/practicepanther-mcp/src/server.ts"],
+      "env": {
+        "PP_ACCESS_TOKEN": "your_token"
+      }
+    }
+  }
+}
 ```
 
 ## Project Structure
 
 ```
 src/
-├── server.ts       # MCP server entry point — registers all tools
-├── schemas.ts      # Zod schemas for shaping API responses
-├── auth.ts         # OAuth2 config (delegates to shared oauth utility)
-├── pp.ts           # Configures generated HTTP client with base URL + auth
-└── client/         # Auto-generated typed API client (do not edit)
+├── server.ts              # Entry point — CLI dispatch (server vs auth)
+├── create-server.ts       # MCP server setup — registers all tools
+├── tool-handler.ts        # Generic tool handler factory
+├── helpers.ts             # Utility functions
+├── auth.ts                # OAuth2 config (delegates to shared oauth utility)
+├── pp.ts                  # Configures generated HTTP client with base URL + auth
+├── client/                # Auto-generated typed API client (do not edit)
+├── *.test.ts              # Tests
+└── ...
 ```
-
-## Adding a New Entity
-
-1. Import the SDK functions from `./client/index.js`
-2. Define a Zod schema in `schemas.ts`
-3. Register `get_` and `list_` tools in `server.ts`