visus-mcp 0.6.0 → 0.6.2

package/.claude/settings.local.json

@@ -14,7 +14,48 @@
       "Bash(git push)",
       "Bash(git push:*)",
       "Bash(npm search:*)",
-      "Bash(npm publish:*)"
+      "Bash(npm publish:*)",
+      "Bash(git tag:*)",
+      "Bash(npm view:*)",
+      "Bash(cat:*)",
+      "Bash(find:*)",
+      "Bash(git checkout:*)",
+      "Bash(node:*)",
+      "WebFetch(domain:mcp.so)",
+      "WebFetch(domain:pulsemcp.com)",
+      "WebFetch(domain:github.com)",
+      "WebFetch(domain:registry.modelcontextprotocol.io)",
+      "Bash(git remote:*)",
+      "Bash(brew install:*)",
+      "Bash(mcp-publisher:*)",
+      "Bash(npm version:*)",
+      "Bash(aws lambda get-function:*)",
+      "Bash(pkill:*)",
+      "Bash(docker info:*)",
+      "Bash(npx esbuild:*)",
+      "Bash(./node_modules/.bin/esbuild:*)",
+      "Bash(node_modules/.bin/esbuild:*)",
+      "Bash(zip:*)",
+      "Bash(aws lambda update-function-code:*)",
+      "Bash(aws lambda get-function-configuration:*)",
+      "Bash(aws sts get-caller-identity:*)",
+      "Bash(aws cognito-idp list-users:*)",
+      "Bash(aws cognito-idp admin-create-user:*)",
+      "Bash(aws cognito-idp admin-set-user-password:*)",
+      "Bash(aws cognito-idp initiate-auth:*)",
+      "Bash(TOKEN=\"eyJraWQiOiJ1eGNRZmJWbWx4WFBaSzdwYisxck5mcmxaaXBHZE5Wekw0WWFmMis5c25ZPSIsImFsZyI6IlJTMjU2In0.eyJzdWIiOiI3NDA4OTRjOC01MDYxLTcwOGMtMzkwYy1mMmIxMmRkOGY4MDciLCJlbWFpbF92ZXJpZmllZCI6dHJ1ZSwiaXNzIjoiaHR0cHM6XC9cL2NvZ25pdG8taWRwLnVzLWVhc3QtMS5hbWF6b25hd3MuY29tXC91cy1lYXN0LTFfOFVLQU9EQWZxIiwiY29nbml0bzp1c2VybmFtZSI6Ijc0MDg5NGM4LTUwNjEtNzA4Yy0zOTBjLWYyYjEyZGQ4ZjgwNyIsIm9yaWdpbl9qdGkiOiJmM2Y2ZjRhNi1lYWE2LTQ1NGMtYjFhMC0xYzY3MzgyNzYyOGMiLCJhdWQiOiIzam9yMTNhdXJjNThybHY4bDZjYW5iN29ldSIsImV2ZW50X2lkIjoiNWYzMWU5YjAtZmIxOS00NWE2LTkxNzEtNWYxYjQyZjcwZjdiIiwidG9rZW5fdXNlIjoiaWQiLCJhdXRoX3RpbWUiOjE3NzQzNTE4MzcsImV4cCI6MTc3NDM1NTQzNywiaWF0IjoxNzc0MzUxODM3LCJqdGkiOiI5ZmYwMzlhMi1hOGVkLTQ3ZWQtYjNiZS1jM2Q1NmU1MGEwM2MiLCJlbWFpbCI6InRlc3QtdXNlckBsYXRlb3MuYWkifQ.XxRcRpHWHNht0aVJMr2MJbDVS1fGBH0YchOjaxaYYBJFbptSRf_J_GT2q1EJLAFm9Ey1FlJvQF_oBpOKRd37DiYwbJZxltmAtlF-7hfiNQwfHnZ6T7oFERQx353RyZL3DHrHE2s6BbDFkJb69xwjuzn4ijMVrsZ_ny3qxHC02Fr37oumwbP_cfey3wjjjmONedUQwX6o0ajUK_Aafk20O-tWFDDUDk1Ua_TdPct0wOztYHcGhxE1Yo_g_mykwKLtI-ZSWiBaGj-GTGidgQ_RCJPKrQPK73xQAePvJMkB6SKlJg5tfnvnB1S_Hnsyg1bR3laZg1M-bP_3eTRAl6le5g\")",
+      "Bash(aws apigateway:*)",
+      "Bash(aws logs describe-log-groups:*)",
+      "Bash(python3:*)",
+      "Bash(echo:*)",
+      "Bash(ID_TOKEN=\"eyJraWQiOiJ1eGNRZmJWbWx4WFBaSzdwYisxck5mcmxaaXBHZE5Wekw0WWFmMis5c25ZPSIsImFsZyI6IlJTMjU2In0.eyJzdWIiOiI3NDA4OTRjOC01MDYxLTcwOGMtMzkwYy1mMmIxMmRkOGY4MDciLCJlbWFpbF92ZXJpZmllZCI6dHJ1ZSwiaXNzIjoiaHR0cHM6XC9cL2NvZ25pdG8taWRwLnVzLWVhc3QtMS5hbWF6b25hd3MuY29tXC91cy1lYXN0LTFfOFVLQU9EQWZxIiwiY29nbml0bzp1c2VybmFtZSI6Ijc0MDg5NGM4LTUwNjEtNzA4Yy0zOTBjLWYyYjEyZGQ4ZjgwNyIsIm9yaWdpbl9qdGkiOiIyMTY0OTkyMy1lMDcwLTRjMWQtYjFmYy1jZjZlODM2Y2E1OTIiLCJhdWQiOiIzam9yMTNhdXJjNThybHY4bDZjYW5iN29ldSIsImV2ZW50X2lkIjoiM2MxNzIwZjgtMTljMS00Y2MxLWI2MDctYWI5NzlmOTIzZGU1IiwidG9rZW5fdXNlIjoiaWQiLCJhdXRoX3RpbWUiOjE3NzQzNTIyNjMsImV4cCI6MTc3NDM1NTg2MywiaWF0IjoxNzc0MzUyMjYzLCJqdGkiOiIyY2Y3MWMwYi1hNzkwLTQzMjItYjQzZC1jZDRjNzIxZjdjZmIiLCJlbWFpbCI6InRlc3QtdXNlckBsYXRlb3MuYWkifQ.ljsffJWON0SykNe00nf1P1X0gtOLd4ccR4EmhRVFucOFulyEpB5Uyjbt3npuTah6liU2ZBTSWjKkdS0olRGFlLipzUMqDPqzINwwjkOMVQK5bf0l3f31FfdeQ_lKiYHKXbEDWJH8TRIvVy3OSl8I5UALn2swXyaWnLOO2mM6gcfYTr7Gt0JhfDohhKnvbr6kbGfCXu8kvp-uPGD4bKc7blmqwwKjaKQ49BukfhF_aC6fuiqsVydbYTO_fWbxTWITD39ULszaNbrGSBr0Q8ljWHC-t3qB9xlbXGOA3wbY13OaIc4P1kvzvQn6atP1FzZ5TSUb-DuDrS2lkGI-jnWjEA\")",
+      "Bash(/tmp/token.txt)",
+      "Bash(chmod:*)",
+      "Bash(/tmp/test-auth.sh)",
+      "Bash(/tmp/test-google.sh:*)",
+      "Bash(git reset:*)",
+      "Bash(npx visus-mcp:*)",
+      "WebSearch"
     ],
     "deny": [],
     "ask": []

package/.github/ISSUE_TEMPLATE/bug_report.md

@@ -0,0 +1,47 @@
+---
+name: Bug Report
+about: Something isn't working correctly
+title: '[BUG] '
+labels: bug
+assignees: ''
+---
+
+## Describe the bug
+
+A clear description of what went wrong.
+
+## Tool used
+
+- [ ] visus_fetch
+- [ ] visus_read
+- [ ] visus_search
+- [ ] visus_fetch_structured
+
+## To Reproduce
+
+1. Tool call (URL and parameters — remove any sensitive URLs)
+2. Expected output
+3. Actual output
+
+## Sanitization metadata
+
+Paste the `sanitization` block from the tool response if relevant.
+
+```json
+{
+  "patterns_detected": [],
+  "pii_types_redacted": [],
+  "content_modified": false
+}
+```
+
+## Environment
+
+- visus-mcp version: (run `npx visus-mcp --version`)
+- Node.js version: (run `node --version`)
+- OS: (macOS / Windows / Linux)
+- Claude Desktop version (if applicable):
+
+## Additional context
+
+Any other relevant information.

package/.github/ISSUE_TEMPLATE/false_positive.md

@@ -0,0 +1,43 @@
+---
+name: False Positive Report
+about: visus incorrectly flagged or redacted legitimate content
+title: '[FALSE POSITIVE] '
+labels: false-positive, sanitizer
+assignees: ''
+---
+
+## What was incorrectly flagged?
+
+Describe the legitimate content that was redacted or blocked.
+Do NOT include sensitive URLs or private content.
+
+## Pattern category that fired
+
+Which pattern triggered? (visible in the `patterns_detected` field of the sanitization metadata)
+
+Pattern name: `pattern_name_here`
+
+## Example of the content
+
+A minimal example of the text that triggered the false positive.
+Keep it short — just enough to reproduce the pattern match.
+
+```
+Example content here
+```
+
+## Expected behavior
+
+What should visus have done with this content?
+
+## Domain context
+
+What type of site was this? (news, documentation, health info, government, etc.) — helps assess if a domain-scoped allowlist is appropriate.
+
+Domain type: ___
+
+## visus-mcp version
+
+Run `npx visus-mcp --version`:
+
+Version: ___

package/.github/ISSUE_TEMPLATE/new_pattern.md

@@ -0,0 +1,49 @@
+---
+name: New Injection Pattern Request
+about: Suggest a new prompt injection pattern category
+title: '[PATTERN] '
+labels: enhancement, sanitizer
+assignees: ''
+---
+
+## Pattern description
+
+What type of injection attack does this detect?
+
+## Example of malicious content
+
+A concrete example of what this pattern should catch.
+(These examples are for security research — they will be added to the test corpus.)
+
+**Example 1 (should be caught):**
+```
+[paste example here]
+```
+
+**Example 2 (should NOT be caught — negative case):**
+```
+[paste legitimate content that looks similar but is safe]
+```
+
+## Proposed severity level
+
+- [ ] CRITICAL — Immediate threat, direct instruction manipulation
+- [ ] HIGH — Significant obfuscation or context manipulation
+- [ ] MEDIUM — Moderate risk, indirect attack vectors
+- [ ] LOW — Low risk, informational flag
+
+## Framework mapping (if known)
+
+- OWASP LLM Top 10: (e.g. LLM01:2025)
+- NIST AI 600-1: (e.g. MS-2.5)
+- MITRE ATLAS: (e.g. AML.T0051)
+- ISO/IEC 42001: (e.g. A.6.1.5)
+
+## Real-world context
+
+Where have you seen this pattern used? (CVE, research paper, red team exercise, etc.)
+
+## Are you willing to submit a PR?
+
+- [ ] Yes, I'll implement and test this pattern
+- [ ] No, but I can provide more examples if needed

package/.github/ISSUE_TEMPLATE/security_report.md

@@ -0,0 +1,31 @@
+---
+name: Security Vulnerability
+about: Report a security vulnerability in visus-mcp
+title: '[SECURITY] '
+labels: security
+assignees: ''
+---
+
+# ⚠️ STOP — Do not file public security issues.
+
+If you have found a security vulnerability in visus-mcp, please report it **privately**:
+
+📧 **Email:** security@lateos.ai
+
+🔒 **GitHub Security Advisories:**
+   https://github.com/visus-mcp/visus-mcp/security/advisories/new
+
+## Include in your report:
+
+- Description of the vulnerability
+- Steps to reproduce
+- Potential impact
+- Suggested fix (optional)
+
+We aim to respond within **48 hours** and will credit you in SECURITY.md once the issue is resolved.
+
+Thank you for helping keep visus-mcp secure.
+
+---
+
+**Do not proceed with this public issue template for security vulnerabilities.**

package/.github/PULL_REQUEST_TEMPLATE.md

@@ -0,0 +1,39 @@
+## What does this PR do?
+
+Brief description of the change.
+
+## Type of change
+
+- [ ] New injection pattern
+- [ ] False positive fix
+- [ ] Bug fix
+- [ ] Feature addition
+- [ ] Documentation update
+- [ ] Performance improvement
+
+## Test results
+
+- [ ] npm test passes (all tests)
+- [ ] npm run build compiles cleanly
+- [ ] New tests added for new functionality
+- [ ] Test count did not decrease
+
+**Before:** X/X tests passing
+**After:** X/X tests passing
+
+## Security checklist
+
+- [ ] All new content passes through the sanitizer pipeline
+- [ ] No new `any` types introduced
+- [ ] No console.log (use structured stderr logging)
+- [ ] No hardcoded secrets or API keys
+- [ ] CLAUDE.md security rules not violated
+
+## Does this change affect sanitization coverage?
+
+- [ ] No
+- [ ] Yes — explain: ___
+
+## Related issues
+
+Closes #___

package/.mcpregistry_github_token

@@ -0,0 +1 @@
+ghu_9xbQ1SXXZ8bh3BmoTNB21qUfmu31cJ0ly3mc

package/.mcpregistry_registry_token

@@ -0,0 +1 @@
+{"token":"eyJhbGciOiJFZERTQSIsInR5cCI6IkpXVCJ9.eyJpc3MiOiJtY3AtcmVnaXN0cnkiLCJleHAiOjE3NzQzMDc2MzIsIm5iZiI6MTc3NDMwNzMzMiwiaWF0IjoxNzc0MzA3MzMyLCJhdXRoX21ldGhvZCI6ImdpdGh1Yi1hdCIsImF1dGhfbWV0aG9kX3N1YiI6Imxlb2Nob25nIiwicGVybWlzc2lvbnMiOlt7ImFjdGlvbiI6InB1Ymxpc2giLCJyZXNvdXJjZSI6ImlvLmdpdGh1Yi5sZW9jaG9uZy8qIn0seyJhY3Rpb24iOiJwdWJsaXNoIiwicmVzb3VyY2UiOiJpby5naXRodWIudmlzdXMtbWNwLyoifV19.qXNypXv1OF_l3ob4Kju46rvn-vs4s5x3JIU2ZH7jJiaBV5gy0sX60NJSKM9ybJvcXggnW9_Mp1L-JeZDPVd5BQ","expires_at":1774307632}

package/CLAUDE.md

@@ -71,6 +71,9 @@ npm publish --dry-run # Validate package before publishing
 npx visus-mcp         # Start MCP server
 ```
 
+**IMPORTANT: On every npm release, keep `server.json` version in sync with `package.json` version.**
+The MCP registry requires that the version field in `server.json` matches the published npm package version.
+
 ## Coding Standards (Lateos Conventions)
 
 - **TypeScript strict mode** - No `any` types allowed
@@ -103,6 +106,8 @@ All tests must pass before Phase 1 is complete.
 - 43 injection payloads (one per pattern category)
 - 10 clean pages/content samples (should produce no detections)
 
+---
+
 ## Standard Troubleshooting Protocol
 
 Whenever you encounter an error, blocked deployment, or multi-step recovery task, you MUST generate a structured troubleshooting log automatically. This is not optional — it applies to every build, fix, and diagnostic task in this project.
@@ -118,6 +123,62 @@ Save to project root. Examples:
 - `TROUBLESHOOT-LAMBDA-20260314-0900.md`
 - `TROUBLESHOOT-SLIM-20260314-0629.md`
 
+### Log Structure
+
+Every troubleshooting log MUST follow this three-phase structure:
+
+#### Phase 1: Investigation (read-only)
+No changes to code or infrastructure. Gather facts, reproduce the error, read logs.
+Only advance to Phase 2 after root cause is confirmed or a clear hypothesis is formed.
+
+#### Phase 2: Fix Plan
+Write out the proposed fix and alternatives considered. Do NOT execute yet.
+If root cause shifts during Phase 2, return to Phase 1.
+
+#### Phase 3: Execution
+Implement the fix. Log every action. Update the SUMMARY at the end.
+
+---
+
+### Stop Conditions (mandatory — check before every action)
+
+If any of the following are true, **STOP immediately**, log the blocker, and wait for user input:
+
+| Condition | Action |
+|-----------|--------|
+| Deployment or build hangs >10 minutes | Kill process, document, ask user for direction |
+| Same error appears >2 times in a row | Stop retrying, propose alternative approach |
+| Root cause shifts away from original task | Re-confirm scope with user before continuing |
+| A tool or service is unavailable (Docker, AWS, etc.) | Document and present options — do not loop |
+| Success criteria cannot be verified | Stop and ask user how to validate |
+
+---
+
+### Environment Pre-flight
+
+Run this checklist before ANY deployment or infrastructure task. Log each result.
+
+```bash
+# AWS credentials
+aws sts get-caller-identity
+
+# Docker health (required for CDK bundling)
+docker info
+
+# Disk space (ENOSPC will cause silent failures)
+df -h /
+
+# CDK version
+npx cdk --version
+
+# Node/npm
+node --version && npm --version
+```
+
+If Docker is unavailable or disk space is low, use the manual Lambda deploy path (see Lambda Deployment below) rather than attempting CDK.
+
+---
+
 ### Entry Format (append after EVERY action)
 
 ```markdown
@@ -130,6 +191,24 @@ Save to project root. Examples:
 **Status:** ✅ Success / ❌ Failed / ⚠️ Partial
 ```
 
+### Ruled Out (maintain throughout session)
+
+Append to this section whenever a suspected cause is eliminated. Prevents re-investigation.
+
+```markdown
+## Ruled Out
+- ❌ <Component>: <one-line reason> — confirmed <date/time>
+```
+
+Example:
+```markdown
+## Ruled Out
+- ❌ Cognito JWT: Auth correctly returns 401 on unauthenticated requests — not the issue
+- ❌ API Gateway routing: Routes confirmed correct in stack outputs — not the issue
+```
+
+---
+
 ### Rules
 
 1. **Log BEFORE executing, not after** — write Goal and Reasoning first
@@ -137,6 +216,25 @@ Save to project root. Examples:
 3. **On failure:** log the full error, state your revised reasoning, attempt one alternative, log that too
 4. **Do not summarize or clean up errors** — paste raw output verbatim
 5. **End every log with a SUMMARY section:** root cause, resolution, lessons learned, and open issues
+6. **Populate "Ruled Out" in real time** — do not re-investigate eliminated causes
+7. **Complete Phase 1 fully before making any changes** — no exceptions
+
+---
+
+### CLAUDE.md Updates Required
+
+At the end of every troubleshooting session, before closing, check whether any findings should be promoted to this file. Add a section to the troubleshoot doc:
+
+```markdown
+## CLAUDE.md Updates Required
+- [ ] <Finding that should become a permanent convention>
+- [ ] <New known error to add to the registry>
+- [ ] <New deployment step or warning>
+```
+
+Then apply those updates to CLAUDE.md as the final step of the session.
+
+---
 
 ### Purpose
 
@@ -152,6 +250,8 @@ Goal: Restore MCP handler Lambda with proper dependency packaging
 
 ---
 
+## Phase 1: Investigation
+
 ## [06:02:18] Step 1 - Locate MCP Handler Source
 
 **Goal:** Find the mcp_handler.py source file in the project
@@ -163,14 +263,109 @@ Goal: Restore MCP handler Lambda with proper dependency packaging
 
 ---
 
+## Ruled Out
+- ❌ IAM permissions: Lambda execution role has correct policies — not the issue
+
+---
+
+## Phase 2: Fix Plan
+...
+
+## Phase 3: Execution
+...
+
+---
+
 # RECOVERY SUMMARY
 
 Final Status: ✅ RESTORED
 Root Cause: Lambda package missing runtime dependencies
 Resolution: Installed aws_lambda_powertools + aws_xray_sdk
 Lessons Learned: Always verify dependencies in Lambda packages
+
+## CLAUDE.md Updates Required
+- [ ] Add aws_lambda_powertools to standard Lambda dependency checklist
+```
+
+---
+
+## Known Errors Registry
+
+When a root cause is confirmed, add it here. Future sessions check this list first before investigating.
+
+| Error | Root Cause | Fix | Date Confirmed |
+|-------|-----------|-----|----------------|
+| `ERR_MODULE_NOT_FOUND: @modelcontextprotocol/sdk` in Lambda | `index.js` (MCP stdio server) included in Lambda bundle via `package.json` `"main"` field; SDK not bundled | Add `@modelcontextprotocol/sdk` to `externalModules` in `infrastructure/stack.ts` | 2026-03-24 |
+| CDK `docker buildx` hangs indefinitely | Docker resource contention or disk pressure on Apple Silicon Mac | Use manual Lambda deploy script (see below); fix Docker separately | 2026-03-24 |
+| `ENOSPC` on Claude Code startup | Mac disk full; `~/.claude/debug/` write fails | Free disk space; `rm -rf ~/.claude/debug/`; restart | 2026-03-24 |
+| 401 Unauthorized after `cdk deploy` | CDK does NOT automatically redeploy API Gateway stages when Lambda code or authorizer config changes | After every `cdk deploy`, run: `aws apigateway create-deployment --rest-api-id <api-id> --stage-name <stage>` | 2026-03-24 |
+| `unable to get local issuer certificate` in Lambda | undici HTTP client in AWS Lambda Node.js 20 runtime lacks proper CA certificate configuration | Replace undici with Node.js native `fetch()` API (available in Node 18+) which has proper CA handling in Lambda | 2026-03-24 |
+
+---
+
+## Lambda Deployment
+
+### Bundling Conventions
+
+**CRITICAL: Always use `--format=cjs` for Lambda bundles.**
+AWS SDK v3 uses dynamic `require()` internally. ESM output from esbuild will fail at Lambda runtime with `ERR_REQUIRE_ESM` or similar. CommonJS is the correct format for all Lambda deployments.
+
+**Always externalize these packages:**
+- `playwright-core` — added via Lambda layer
+- `@sparticuz/chromium` — added via Lambda layer
+- `@modelcontextprotocol/sdk` — only needed for stdio mode, not Lambda
+
+**Entry point must always be `src/lambda-handler.ts`, NOT `src/index.ts`.**
+`index.ts` is the MCP stdio server and imports packages that must not be in the Lambda bundle.
+
+### Manual Deploy Script (use when CDK/Docker is unavailable)
+
+```bash
+#!/bin/bash
+# scripts/deploy-lambda.sh
+# Use this when CDK Docker bundling is blocked
+
+set -e
+
+echo "Building Lambda bundle..."
+npm run build
+
+npx esbuild src/lambda-handler.ts \
+  --bundle \
+  --platform=node \
+  --target=node20 \
+  --format=cjs \
+  --outfile=dist/lambda-bundle.js \
+  --external:playwright-core \
+  --external:@sparticuz/chromium \
+  --external:@modelcontextprotocol/sdk \
+  --sourcemap
+
+echo "Zipping..."
+cd dist && zip -r ../lambda.zip lambda-bundle.js lambda-bundle.js.map && cd ..
+
+echo "Getting function name..."
+FUNCTION_NAME=$(aws cloudformation describe-stacks \
+  --stack-name VisusStack-dev \
+  --query "Stacks[0].Outputs[?OutputKey=='LambdaFunctionName'].OutputValue" \
+  --output text)
+
+echo "Deploying to Lambda: $FUNCTION_NAME"
+aws lambda update-function-code \
+  --function-name "$FUNCTION_NAME" \
+  --zip-file fileb://lambda.zip
+
+echo "Waiting for update..."
+aws lambda wait function-updated --function-name "$FUNCTION_NAME"
+
+echo "Testing health endpoint..."
+curl -s https://3lsush2fx0.execute-api.us-east-1.amazonaws.com/dev/health | jq .
+
+echo "Done. Check CloudWatch for ERR_MODULE_NOT_FOUND — should be gone."
 ```
 
+After using manual deploy, run a full `cdk deploy` when Docker is restored to keep CloudFormation state in sync with live infrastructure.
+
 ---
 
 ## CRITICAL: Security Rules — Never Violate These
@@ -240,6 +435,8 @@ lateos-visus/
 │   ├── browser/
 │   │   └── playwright-renderer.ts  # Headless Chromium page fetcher
 │   └── types.ts                    # Shared TypeScript interfaces
+├── scripts/
+│   └── deploy-lambda.sh            # Manual Lambda deploy (bypasses CDK/Docker)
 └── tests/
     ├── sanitizer.test.ts
     ├── fetch-tool.test.ts