@mtaap/mcp 0.1.2 → 0.2.0

package/README.md

@@ -12,6 +12,15 @@ npm install -g @mtaap/mcp
 npx @mtaap/mcp
 ```
 
+## Architecture
+
+The MCP server is a thin API client that communicates with the MTAAP webapp via REST API. All business logic, database access, and encryption operations are handled server-side by the webapp. This design:
+
+- **Simplifies configuration**: Only 2 environment variables required
+- **Improves security**: No encryption keys or database credentials in user configs
+- **Reduces package size**: ~90% smaller than direct database access version
+- **Centralizes logic**: All business rules enforced server-side
+
 ## Configuration
 
 ### Required Environment Variables
@@ -19,18 +28,19 @@ npx @mtaap/mcp
 | Variable | Description |
 |----------|-------------|
 | `MTAAP_API_KEY` | Your MTAAP API key. Generate one at https://collab.mtaap.de/settings/api-keys |
+| `MTAAP_BASE_URL` | MTAAP webapp URL (e.g., `https://collab.mtaap.de`) |
 
 ### Optional Environment Variables
 
 | Variable | Description |
 |----------|-------------|
-| `GITHUB_TOKEN` | GitHub personal access token for branch creation and PR features |
+| `MTAAP_DEBUG` | Set to `true` to enable debug logging |
 
 ### Example
 
 ```bash
 export MTAAP_API_KEY=usr_xxxxx...
-export GITHUB_TOKEN=ghp_xxxxx...  # Optional, for git operations
+export MTAAP_BASE_URL=https://collab.mtaap.de
 ```
 
 ## Available Tools
@@ -246,7 +256,7 @@ pnpm build
 pnpm dev
 
 # Run locally
-MTAAP_API_KEY=your-key pnpm start
+MTAAP_API_KEY=your-key MTAAP_BASE_URL=https://collab.mtaap.de pnpm start
 ```
 
 ## Troubleshooting
@@ -255,17 +265,25 @@ MTAAP_API_KEY=your-key pnpm start
 
 You need to set the `MTAAP_API_KEY` environment variable. Generate an API key at https://collab.mtaap.de/settings/api-keys
 
-### "GITHUB_TOKEN is not set" warning
+### "MTAAP_BASE_URL is required"
 
-This warning appears when `GITHUB_TOKEN` is not configured. Git operations (branch creation, PR creation) require this token. The server will still start, but git-related features will fail.
+You need to set the `MTAAP_BASE_URL` environment variable to your MTAAP webapp URL (e.g., `https://collab.mtaap.de`).
 
-### "Invalid API key"
+### "Invalid API key" or "Authentication failed"
 
 Your API key may be expired or revoked. Generate a new one at https://collab.mtaap.de/settings/api-keys
 
+### "GitHub token not configured"
+
+Git operations (branch creation, PR creation) require a GitHub token to be configured in your MTAAP account settings. Go to https://collab.mtaap.de/settings and add your GitHub personal access token.
+
 ### Connection issues
 
-Ensure your firewall allows outbound connections to your MTAAP instance. By default, the server connects to `https://collab.mtaap.de`.
+Ensure your firewall allows outbound connections to your MTAAP instance. The server performs a connectivity check on startup and will report any connection issues.
+
+### Rate limiting
+
+The MCP API is rate limited to 100 requests per minute. If you exceed this limit, you'll receive a 429 error with a `Retry-After` header indicating when you can retry.
 
 ## Publishing