MCP server for the Handbook API – manage handbook entries via CRUD, overview and tag search.
The Handbook MCP server provides 7 well-named tools with comprehensive schemas and descriptions. Tool names follow verb_noun convention (handbook_list_entries, handbook_get_entry, handbook_create_entry, etc.), which is excellent for LLM parsing. All tools have clear descriptions (100-250 chars range), and input schemas use Zod with proper type definitions and descriptions. However, there are gaps in output schema documentation, error handling guidance, and security considerations. The server lacks pagination support for potentially large result sets (list_entries could return many items), and descriptions don't include recovery guidance for error cases. Parameter descriptions are thorough but some lack format/constraint specifications beyond type definitions. The code shows good organization with separation of concerns (schemas, services, formatting), but the tool responses rely on text formatting rather than structured JSON responses.
Create a new handbook entry. Args: - title (string): Entry title - content (string, optional): Markdown content - active (boolean): Whether the entry is active - app (string): App identifier (e.g. 'szales', 'sethub') - tags (string[], optional): Tags - importId (string, optional): Import ID Returns: The created HandbookEntry.
Permanently delete a handbook entry by ID. Args: - id (string): ID of the entry to delete Returns: Confirmation of deletion.
Retrieve a single handbook entry by its ID, including full content in markdown. Args: - id (string): The MongoDB ObjectId of the entry Returns: Full HandbookEntry object with content.
Get a lightweight overview of all handbook entries for a specific app. Returns only title, ID, app and tags (no full content). Args: - app (string): App identifier (e.g. 'szales', 'sethub') Returns: HandbookOverviewResponse with an array of overview entries.
Retrieve all handbook entries. Returns a list with title, ID, app, active status and tags for every entry. Returns: Array of HandbookEntry objects. Use when: you need an overview of all existing entries or want to find an entry ID.
No pagination support for list operations. handbook_list_entries returns all entries without limit/offset parameters, risking context window explosion for large datasets. The CHARACTER_LIMIT truncation (50KB) is a band-aid; proper pagination is required.
Output schemas not documented. While input schemas are well-defined via Zod, the server does not document what HandbookEntry, HandbookOverviewEntry, or HandbookTagsResponse structures contain. LLMs cannot reliably plan downstream calls without knowing return field names and types.
Error handling lacks recovery guidance. API errors (api-client.ts line ~50) throw generic 'API request failed' messages without suggesting what the LLM should do next (retry, call search_*, ask user for input, etc.). No distinction between retryable, user-fixable, or fatal errors.
| Scored | Grade | Overall | Spec posture | Rubric |
|---|---|---|---|---|
| 2026-09-22 | C | 63 | 2025-06-18+ | v2 |
| 2026-03-09 | D | 51 | - | v1 |
Search for tags across all handbook entries. Args: - searchQuery (string): Search string to filter tags (e.g. 'meet') Returns: HandbookTagsResponse with an array of matching tag strings.
Update an existing handbook entry by ID. Args: - id (string): ID of the entry to update - title (string): Updated title - content (string, optional): Updated markdown content - active (boolean): Active status - app (string): App identifier - tags (string[], optional): Updated tags - importId (string, optional): Import ID Returns: The updated HandbookEntry.
Destructive tool (handbook_delete_entry) lacks confirmation or dry-run. Agents can permanently delete entries with a single call. No pre-confirmation step or soft-delete option exists to prevent catastrophic mistakes.
No tool annotations despite having toolAnnotations=true. The code registers tools (handbook-entry.ts) but does not attach readOnlyHint, destructiveHint, or idempotentHint metadata. These hints help LLMs reason about side effects and retry safety.
Sensitive parameter not guarded. HANDBOOK_API_TOKEN is required as an environment variable and validated at runtime (api-client.ts), which is correct. However, there is no explicit documentation in tool descriptions that credentials are server-injected (not user-provided), which could mislead users.
Parameter constraints not fully specified. 'app' parameter (e.g. 'szales', 'sethub') is documented as a string with examples, but no enum constraint exists. LLMs may invent invalid app names; an enum would prevent this.
Response formatting as text rather than structured output. Tools return markdown-formatted strings (formatEntry, formatEntryList, formatOverview in formatting.ts) instead of JSON objects. This wastes tokens, is harder for LLMs to parse, and invites hallucination when extracting values from prose.
No idempotency guarantee. handbook_create_entry does not accept an idempotency_key or check for duplicates. If an agent retries after a transient error, a duplicate entry will be created.
Missing permission/scope declaration. Tools do not declare what permissions they require (e.g. 'read:handbook', 'write:handbook'). This prevents least-privilege configurations and makes audit trails ambiguous.