MCP Server for Apache Lucene - provides full-text search and indexing capabilities via Model Context Protocol
The server defines 5 tools with explicit JSON schemas and descriptions visible in mcp-shim/server.js. However, critical gaps in parameter documentation, missing output schema specifications, and lack of error recovery guidance significantly limit quality. Tools are properly named with action verbs (lucene_status, lucene_upsert, lucene_query, lucene_delete, lucene_list), which is a positive. However, parameter descriptions are entirely absent, none of the input schema properties include 'description' fields. Tool descriptions are present but generic (34-61 chars on average, below the baseline median of 194 chars). The server provides no documentation of output schemas, making it impossible for LLMs to know what fields to expect and plan downstream operations. Error handling in server.js catches exceptions but returns unstructured error content without actionable recovery guidance. No input validation, no enums for constrained values, and no explicit documentation of expected formats, ranges, or side effects.
Delete documents by ids.
List documents with pagination (limit, offset).
Query Lucene index with optional metadata filter and top_k.
Get status of the Lucene MCP server (index path, doc count).
Upsert documents into Lucene index.
Zero parameter descriptions across all tools. Input schemas define structure (type, required, properties) but omit description fields for every parameter. LLMs cannot infer what 'documents', 'queries', 'ids', 'limit', 'offset', 'filter', 'top_k' actually control or expect as input format.
No output schema documentation. Tool descriptions state what they do (e.g., 'Query Lucene index') but never describe the return value structure. LLMs cannot predict what fields are available for chaining or what the response looks like.
Tool descriptions are below minimum quality threshold (34 - 61 chars). Baseline for A+ tools is 50 - 200 chars. Examples: 'Get status of the Lucene MCP server (index path, doc count).' is 57 chars but lacks WHEN to use it or prerequisites. 'Query Lucene index with optional metadata filter and top_k.' is 59 chars but does not explain what a 'filter' is or what 'top_k' does.
| Scored | Grade | Overall | Spec posture | Rubric |
|---|---|---|---|---|
| 2026-09-22 | F | 11 | 2026-07-28+ | v2 |
| 2026-03-09 | F | 37 | - | v1 |
No constrained inputs (enums, min/max, patterns). 'top_k' and 'limit' and 'offset' are numbers with no bounds documented. LLMs can pass absurd values (top_k=999999, limit=-1) that break the index or cause timeouts. No regex patterns for 'id', 'text', 'query', or 'metadata' fields.
Error handling is unstructured. server.js catches errors and returns raw HTTP response bodies or error messages. No error categorization (retryable vs. user-fixable vs. fatal), no invalid value reporting, and no recovery guidance. E.g., if lucene_query fails because the index is missing, the LLM gets a generic 500 error with no hint to call lucene_status first.
lucene_delete has no confirmation step or dry-run option. This is a destructive operation that permanently removes documents. No pattern::confirmation-request implementation. An agent calling lucene_delete with incorrect IDs will silently destroy data with no undo path.
Missing side-effect declarations. Tool descriptions do not state whether they modify state. LLMs cannot infer which tools are safe to retry. 'lucene_upsert' could be idempotent (if IDs are unique), but this is not documented. 'lucene_delete' is destructive but lacks explicit language.
Parameter name ambiguity: 'filter' in lucene_query is undefined. Is it a key-value pair for metadata? A Lucene query syntax string? An object with field:value? Description is missing, and schema shows 'additionalProperties: {type: string}' with no explanation.
No metadata field specification in lucene_upsert. The 'metadata' parameter is declared as {type: object, additionalProperties: {type: string}} but the description never explains what keys are valid, what they control, or how they are indexed/queried.
lucene_status returns index metadata but output schema is not specified. What fields does the response include? (e.g., index_path, doc_count, index_size, last_updated?) LLMs cannot use this data for downstream decisions without explicit schema.