Merge pull request #15 from SkyflowFoundry/jstjoe/anon-mode

Add anonymous mode for unauthenticated requests

Author: jstjoe

.env.sample

@@ -9,3 +9,14 @@ ACCOUNT_ID=""
 
 # Note: SKYFLOW_API_KEY and REQUIRED_BEARER_TOKEN are no longer used
 # The bearer token is now passed through from the client to Skyflow
+
+# Anonymous Mode Configuration
+# When set, allows unauthenticated requests with limited functionality
+# Only the 'dehydrate' tool works in anonymous mode (with ENTITY_UNIQUE_COUNTER tokens)
+ANON_MODE_API_KEY=""          # Skyflow API key for demo vault
+ANON_MODE_VAULT_ID=""         # Demo vault ID
+ANON_MODE_VAULT_URL=""        # Demo vault URL (e.g., https://demo.vault.skyflowapis.com)
+
+# Anonymous Mode Rate Limiting
+ANON_MODE_RATE_LIMIT_REQUESTS=10    # Max requests per window (default: 10)
+ANON_MODE_RATE_LIMIT_WINDOW_MS=60000  # Window duration in milliseconds (default: 1 minute)

.vercel/project.json

@@ -1 +1 @@
-{"projectId":"prj_O92h6fOjuzj1Csx68wrJSEEtCS08","orgId":"team_EHvZvBIOBvSYYsZJZEQ2rcnO","projectName":"sky-mcp-streamable"}
+{"projectId":"prj_O92h6fOjuzj1Csx68wrJSEEtCS08","orgId":"team_w0Tg32Q0GT1KuUyTBaZpLg8G","projectName":"sky-mcp-streamable"}

CLAUDE.md

@@ -76,9 +76,10 @@ curl -X POST "http://localhost:3000/mcp?vaultId={vault_id}&vaultUrl={vault_url}"
 ### Tool Implementations
 
 **dehydrate tool**
-- Detects and replaces sensitive information with vault tokens
+- Detects and replaces sensitive information with tokens
 - Returns processed text with word/character counts
-- Uses `TokenFormat` with `VAULT_TOKEN` type
+- Uses `TokenFormat` with `VAULT_TOKEN` type in authenticated mode, `ENTITY_UNIQUE_COUNTER` in anonymous mode
+- In anonymous mode, adds `anonymousMode: true` and a note to the response
 - Has commented-out support for custom regex allow/restrict lists
 
 **rehydrate tool**
@@ -139,6 +140,32 @@ Fallback method (API key via query parameter):
 https://your-server.com/mcp?vaultId={vault_id}&vaultUrl={vault_url}&accountId={account_id}&workspaceId={workspace_id}&apiKey={your_skyflow_api_key}
 ```
 
+## Anonymous Mode
+
+When no credentials are provided in a request, the server can operate in "anonymous mode" if the following environment variables are configured:
+
+**Environment Variables for Anonymous Mode**:
+- `ANON_MODE_API_KEY`: Skyflow API key for demo vault
+- `ANON_MODE_VAULT_ID`: Demo vault identifier
+- `ANON_MODE_VAULT_URL`: Demo vault URL (e.g., `https://demo.vault.skyflowapis.com`)
+- `ANON_MODE_RATE_LIMIT_REQUESTS`: Max requests per window (default: 10)
+- `ANON_MODE_RATE_LIMIT_WINDOW_MS`: Window duration in milliseconds (default: 60000)
+
+**Tool Behavior in Anonymous Mode**:
+
+| Tool | Anonymous Mode | Authenticated Mode |
+|------|---------------|-------------------|
+| `dehydrate` | Works with `ENTITY_UNIQUE_COUNTER` tokens | Works with `VAULT_TOKEN` tokens |
+| `rehydrate` | Returns error with setup instructions | Works normally |
+| `dehydrate_file` | Returns error with setup instructions | Works normally |
+
+**Token Format Difference**:
+- **Anonymous mode**: Uses `TokenType.ENTITY_UNIQUE_COUNTER` - generates tokens like `[EMAIL_ADDRESS_1]`, `[SSN_2]`. Data is NOT persisted to vault.
+- **Authenticated mode**: Uses `TokenType.VAULT_TOKEN` - generates tokens like `[EMAIL_ADDRESS_abc123xyz]` that are stored in the vault and can be rehydrated.
+
+**Rate Limiting**:
+Anonymous mode requests are rate-limited based on client IP address. When the limit is exceeded, a 429 response is returned with `X-RateLimit-*` headers indicating when the limit resets.
+
 ## Port Configuration
 
 - **3000**: MCP server (configurable via `PORT` env var)
@@ -212,9 +239,12 @@ All tools return both text and structured content:
 return {
   content: [{ type: "text", text: JSON.stringify(output) }],
   structuredContent: output,
+  isError: true, // Optional: set to true when tool returns an error condition
 };
 ```
 
+The `isError` property is set to `true` when a tool returns an error condition (e.g., when `rehydrate` or `dehydrate_file` are called in anonymous mode, or when Skyflow API returns an error). This allows MCP clients to distinguish between successful responses and error responses.
+
 ## Dependencies
 
 - `@modelcontextprotocol/sdk`: Official MCP TypeScript SDK (v1.19.1+)
@@ -228,8 +258,10 @@ return {
 
 1. **Don't reuse transport or Skyflow instances** - Always create new ones per request
 2. **File size limits** - Base64 encoding adds ~33% overhead; 5MB limit means ~3.75MB original files
-3. **Credentials required** - All `/mcp` requests must include either valid `Authorization: Bearer <token>` header with a Skyflow bearer token OR `apiKey` query parameter with a Skyflow API key
-4. **Query parameters required** - `vaultId` and `vaultUrl` must be provided (via query params or env vars)
+3. **Credentials or anonymous mode required** - All `/mcp` requests must include valid credentials OR anonymous mode must be configured via `ANON_MODE_*` environment variables
+4. **Query parameters required** - `vaultId` and `vaultUrl` must be provided (via query params or env vars) - unless using anonymous mode
 5. **Vault configuration** - `clusterId` is automatically extracted from `vaultUrl`, don't set it separately
 6. **Entity type validation** - Use exact strings from `ENTITY_MAP` keys, not the enum values
-7. **AsyncLocalStorage context** - Tools must run within the request context to access Skyflow instance via `getCurrentSkyflow()`
+7. **AsyncLocalStorage context** - Tools must run within the request context to access Skyflow instance via `getCurrentSkyflow()` and `isAnonymousMode()`
+8. **Anonymous mode limitations** - Only the `dehydrate` tool works in anonymous mode; `rehydrate` and `dehydrate_file` return errors with setup instructions
+9. **Keep schemas in sync** - When modifying tool inputs or return values, always update the corresponding `inputSchema` and `outputSchema` in the tool registration. The schemas must match the actual implementation.

README.md

@@ -155,6 +155,54 @@ Create a `.env.local` file with optional fallback values:
 
 **Note**: `SKYFLOW_API_KEY` and `REQUIRED_BEARER_TOKEN` are no longer used. The bearer token is now passed through from the client to Skyflow.
 
+## Anonymous Mode (Try Before You Buy)
+
+You can try the dehydrate tool without configuring Skyflow credentials. When no credentials are provided and anonymous mode is enabled on the server, limited functionality is available.
+
+### Quick Start (Anonymous)
+
+```bash
+# No credentials needed!
+curl -X POST "https://pii-mcp.dev/mcp" \
+  -H "Content-Type: application/json" \
+  -H "Accept: application/json, text/event-stream" \
+  -d '{"jsonrpc":"2.0","method":"tools/call","params":{"name":"dehydrate","arguments":{"inputString":"My email is john@example.com and my SSN is 123-45-6789"}},"id":1}'
+```
+
+### Limitations in Anonymous Mode
+
+- **Only `dehydrate` tool available** - `rehydrate` and `dehydrate_file` return helpful errors
+- **Tokens use entity counters** - e.g., `[EMAIL_ADDRESS_1]`, `[SSN_2]` instead of vault tokens
+- **Data is NOT persisted** - tokens cannot be rehydrated later
+- **Rate limited** - 10 requests per minute per IP (configurable by server operator)
+
+### Claude Desktop (Anonymous)
+
+To use anonymous mode with Claude Desktop:
+
+```json
+{
+  "mcpServers": {
+    "skyflow-pii-demo": {
+      "command": "npx",
+      "args": ["mcp-remote", "https://pii-mcp.dev/mcp"]
+    }
+  }
+}
+```
+
+To unlock full functionality (rehydrate, file processing, persistent vault tokens), configure your Skyflow credentials as shown in the sections above.
+
+### Server Configuration for Anonymous Mode
+
+Server operators can enable anonymous mode by setting these environment variables:
+
+- `ANON_MODE_API_KEY`: Skyflow API key for demo vault
+- `ANON_MODE_VAULT_ID`: Demo vault identifier
+- `ANON_MODE_VAULT_URL`: Demo vault URL
+- `ANON_MODE_RATE_LIMIT_REQUESTS`: Max requests per window (default: 10)
+- `ANON_MODE_RATE_LIMIT_WINDOW_MS`: Window duration in ms (default: 60000)
+
 ## Testing
 
 **Note**: All requests require authentication and configuration. Replace placeholders with your actual values:

package.json

@@ -24,6 +24,7 @@
 	"devDependencies": {
 		"@types/express": "^5.0.3",
 		"@types/node": "^24.10.1",
+		"@vitest/coverage-v8": "^4.0.18",
 		"typescript": "^5.9.3",
 		"vitest": "^4.0.8"
 	}