v0.2.0 quality pass: MCP best-practices alignment from mcp-builder review

[prPMDev]

Context

Post-publish review of jd-intel-mcp@0.1.0 against the mcp-builder skill's best-practices reference. Current state is a solid B+ — production-worthy, real users can install and get value. This issue tracks the P0 quality items that would lift it to A- without major refactor.

Effort estimate: ~1 hour of focused work, single commit.

Checklist (P0 items — ship together as v0.2.0)

1. Add annotations to all three tools

Clients use these to understand tool behavior. All three of our tools are:

• readOnlyHint: true
• destructiveHint: false
• idempotentHint: true
• openWorldHint: true for fetch_jobs and detect_ats (hit external APIs); false for search_registry (local JSON only)

Add to server.registerTool() calls in mcp/tools.js.

2. Add .strict() to Zod schemas

Current schemas are passed as plain object literals ({ field: z.string() }). Convert to z.object({...}).strict(). Rejects extra fields explicitly — gives the AI clear feedback instead of silent ignore.

3. Add pagination metadata to fetch_jobs

Currently we truncate at limit with no signal. Best practice: return has_more, next_offset, total_count. Add offset to inputSchema. Update success() metadata to include pagination fields.

4. Set isError: true on error responses

Our envelope has status: "error" inside content JSON, but the MCP protocol-level isError flag isn't set. MCP clients use the protocol flag for UX treatment (red text, retry hints). Add isError: true to the envelope when status is error or partial_failure. Keep our structured error code/message intact.

5. Add CHARACTER_LIMIT constant + truncation

A fetch_jobs call for a 400-job company with full JDs can blow past 200K characters. Add:

• `CHARACTER_LIMIT = 25000` constant
• After filtering/assembly in `fetch_jobs`, if JSON serialized exceeds limit, truncate jobs array to fit, add `truncated: true` and `truncation_message` to metadata

Explicitly NOT changing (breaking changes)

• Package name `jd-intel-mcp` — convention suggests `-server` suffix; renaming now would orphan installed users
• Tool names (`fetch_jobs` etc.) — convention suggests service prefix (`jd_intel_fetch_jobs`); same reason
• Envelope structure — working in production, consistent across tools

After v0.2.0

Bump version to 0.2.0 in both `package.json` files. Republish both packages. Users on 0.1.0 get the improvements on next `npx -y jd-intel-mcp` (cache expires in ~1 hour).

Reference

Audit performed using Anthropic's mcp-builder skill against MCP best practices. Full audit notes in session log.