MCP server for Magi Archive wiki - provides AI agents secure access to the Magi Archive knowledge base with search, create, and manage cards with role-based permissions
The server defines 30 tools with reasonable naming conventions and mostly complete input schemas. However, output schemas are entirely undocumented, the rubric requires documented return types for all tools, and LLMs cannot plan downstream calls without knowing what fields to expect. Descriptions are present but generic (many lack context on WHEN to use the tool or dependencies). Error handling is not visible in the source. Security considerations (permission gates, audit logging) are mentioned in docstrings but not verified in implementation. The toolset is well-organized around a single domain (card management) but lacks composition details and pagination guidance in several tools.
Append content to an existing card with optional separator.
Create a new card with the specified name, content, and type. Requires appropriate permissions (user role can create basic cards).
Delete a card (move to trash). Requires appropriate permissions (admin role or card owner).
Download a database backup file with checksum verification.
Download an existing backup file by filename with checksum verification.
Iterate over card search results page by page. More memory-efficient than fetch_all_cards for large result sets.
Output schemas are entirely undocumented. The rubric requires 100% of A+ tools to have documented return types. None of the 30 tools specify what fields the response will contain, their types, or structure. This forces LLMs to blind-call tools and parse responses without schema guidance, increasing errors and wasting tokens.
| Scored | Grade | Overall | Spec posture | Rubric |
|---|---|---|---|---|
| 2026-09-22 | D | 57 | 2026-07-28+ | v2 |
| 2026-03-09 | D | 50 | - | v1 |
Fetch all cards matching search criteria. Automatically handles pagination and returns all matching cards. Optionally yields each card to a block for iteration.
Find and replace text in a card's content.
Search within a card's content and return matching positions with context.
Return all tags in the system.
Get a single card by name. Fetches a card with all its metadata, content, and optionally its children.
Fetch the revision history of a card.
Get a card's heading structure and outline without fetching full content.
Get tags for a specific card.
Get cards that link to a given card.
Get cards that a given card links to.
Get cards that nest a given card.
Get cards that a given card nests.
Get cards that reference (link to) a given card.
Fetch a specific revision of a card by act_id.
List all child cards of a parent. Gets the children of a compound card (e.g., 'Parent+Child' cards).
List cards currently in the trash.
Prepend content to an existing card with optional separator.
Restore a card from trash or to a previous revision.
Search for cards with a specific tag.
Search for cards with multiple tags (AND logic).
Search for cards with any of the specified tags (OR logic).
Search for cards by query string, optionally filtered by type. Returns paginated results.
Submit feedback about MCP agent operations to the MCP Agent Feedback+log card.
Update an existing card's content, type, or other metadata.
Tool descriptions lack context on WHEN to use the tool and dependencies. The rubric specifies descriptions should answer: What does it do? When should the LLM call it instead of a similar tool? What does it return? Examples: 'search_by_tag' (60 chars) vs 'search_by_tags' (60 chars) and 'search_by_tags_any' (60 chars) are semantically different but descriptions are identical. 'list_children' does not explain what 'depth' parameter means or when to adjust it. 'fetch_all_cards' vs 'search_cards', when should the LLM use one over the other?
Error handling and recovery guidance is not visible in tool definitions. The rubric requires error responses to tell the LLM what to do next and categorize errors as retryable, user-fixable, or fatal. No tool documents what exceptions it can throw, when they occur, or how to recover. Example: get_card docstring mentions 'Client::NotFoundError' but does not specify what the LLM should do if a card doesn't exist (should it search? suggest alternatives?).
Conflicting tool pairs create ambiguity. 'search_cards' with parameter 'q' vs 'search_by_tag' vs 'search_by_tags' vs 'search_by_tags_any', LLMs will waste reasoning cycles deciding which to call. Similarly, 'fetch_all_cards' vs 'search_cards' (with pagination) and 'each_card_page' vs 'fetch_all_cards' are overlapping. The rubric states: 'Avoid multiple tools that do the same thing differently.' Consolidate into one canonical search interface.
Destructive operations lack confirmation or dry-run support. 'delete_card' is DESTRUCTIVE and 'restore_card' can only recover if 'from_trash=true', but there is no confirmation step. The rubric requires: 'Irreversible operations should support a dry-run or confirmation step. Agents make mistakes, a confirm_before_execute pattern prevents catastrophic errors.' A careless agent in a loop could delete many cards without approval.
Permission gates and scope declarations are documented in comments but not enforced at the tool definition level. The rubric requires each tool to declare what permissions it requires (e.g., 'read:card', 'write:card', 'delete:card'). The tool definitions do not specify this. Example: 'delete_card' docstring states 'Requires appropriate permissions (admin role or card owner)' but there is no formal scope field or permission annotation in the schema.
Pagination limits are not enforced or documented consistently. 'search_cards' specifies 'max: 100' in description, 'list_children' specifies 'max: 100', but 'fetch_all_cards' says 'default: 50' without a max. The rubric requires: 'Specify minimum and maximum for numeric parameters (e.g. page_size 1 - 100, days 1 - 365). Unbounded numbers let LLMs pass absurd values.' Also, responses should document total count or next_cursor for proper pagination planning.
Tag search tools have near-identical names and descriptions ('search_by_tag' vs 'search_by_tags' vs 'search_by_tags_any'). The rubric states: 'When multiple tools operate on the same resource, their names must make the distinction obvious.' Current names are confusing. Recommend: 'search_cards_by_tag' (singular), 'search_cards_by_tags_all' (AND), 'search_cards_by_tags_any' (OR) to clarify the logic and make clear these search the same resource.
'get_all_tags' has an empty input schema ({}), but no description of what it returns. The rubric specifies: 'Document the output schema. LLMs need to know what fields to expect.' What is the structure of the response? Is it an array of strings? Objects with name/count? Without schema, LLMs cannot parse the response reliably.
No tool annotations (readOnlyHint, destructiveHint, idempotentHint) are visible in the source. The rubric rewards adoption of tool annotations for current spec alignment. These hint to LLMs and clients which operations are safe to retry or cache. Example: 'get_card' should be marked readOnlyHint: true; 'delete_card' should be marked destructiveHint: true.