Improve MCP client compatibility defaults

[RitwijParmar]

Summary

• make the default HYPERSPELL_USE_RESOURCES mode tools-only, matching the README and Claude Desktop guidance
• fix the Claude Desktop example to use HYPERSPELL_USE_RESOURCES instead of USE_RESOURCES
• rename registered MCP tools to snake_case names accepted by current MCP tool-name validation

Why

The README says resources are disabled by default because some MCP clients do not support resources well, but the server default was true. Following the Claude Desktop example also set USE_RESOURCES, which the server never reads. While verifying the change with the current MCP SDK, tool registration emitted compatibility warnings for names containing spaces, so this PR also keeps the same descriptions while using stable MCP-safe tool names.

Verification

• PYTHONPATH=src .venv/bin/python config assertion script for default and both modes
• .venv/bin/python -m compileall -q src
• git diff --check

[entelligence-ai-pr-reviews]

---

Confidence Score: 5/5 - Safe to Merge

Safe to merge — this PR improves MCP client compatibility defaults with no identified issues across all reviewed files. The changes appear to be well-scoped default configuration improvements that enhance interoperability without introducing logic bugs, security concerns, or breaking changes. Both changed files were reviewed with full coverage and zero substantive comments were generated.

Key Findings:

• All 2 changed files were reviewed and no issues were identified — no null-check gaps, no logic errors, no security concerns, and no breaking API changes detected in the compatibility default adjustments.
• The PR's stated goal of improving MCP client compatibility defaults is a low-risk, additive change that aligns with a conservative 'better defaults' pattern, which typically carries minimal regression risk.
• Zero unresolved pre-existing review comments exist on this PR, meaning there is no carry-forward technical debt or disputed logic that could affect correctness.

[firetiger-agent]

Monitoring Plan: MCP Tool Name Normalization & Default Mode Flip

What this PR does: Renames all MCP tool identifiers from human-readable strings to snake_case (e.g. "Search Hyperspell" → "search_hyperspell", "Add File" → "add_file") and flips the HYPERSPELL_USE_RESOURCES default from "true" to "false", so new installs expose tools by default instead of MCP resources. Also fixes a wrong env var name in the README's Claude Desktop config example.

Intended effect: No server-side telemetry signal changes at deploy time — this is a client-side package distributed to end users, not a deployed service. Confirmation: API call volume to POST /memories/query stays near its 24h baseline (~73K calls/24h, P50 710ms, P95 1132ms), indicating MCP-originated search traffic continues normally after users upgrade.

Risks:

• Broken tool invocations for existing users — any MCP client configured with old tool names ("Search Hyperspell", "Add File", etc.) will silently fail to invoke those tools after upgrading; no server-side error emitted. Alert: user-reported invocation failures within 48h of package publish.
• Unintended default mode switch — users relying on the implicit use_resources=true default (without setting the env var) will get tools mode instead; alert: user reports of missing resources interface within 48h of publish.
• Invalid env var in existing Claude Desktop configs — users who had USE_RESOURCES (wrong name) in their config will now see it silently ignored (was already broken, but this README fix surfaces the discrepancy); alert: any new auth or 500 errors on the API search path above 5% error rate.

Status updates will be posted automatically on this PR as monitoring progresses.

View agent