v0.8.1: bring MCP instructions block into parity with SKILL.md / v0.8.0

The handshake `instructions` are the ONLY guidance a skill-less client
(ChatGPT via the remote connector) gets, so they must carry what SKILL.md
gives Claude. Two fixes:

- Correct the stale single-substring `search` guidance: the unified `search`
  has tokenized + ANDed terms since v0.7.0, so a multi-word query narrows
  rather than "returns little". Disambiguate it from the search_* `keyword`
  filters (one literal substring -> one term per call).
- Add a RESULTS & ERRORS paragraph mirroring SKILL.md: pagination envelope +
  total_matches, visible limit caps (requested_limit/limit_warning), validated
  enum filters (invalid -> {error,valid_values}; valid + 0 rows = real
  absence), unvalidated free-text filters, and list_locations/list_persons
  mentioned-in semantics.

smoke-test now asserts the served instructions reflect v0.8 (valid_values,
"mentioned in records from", requested_limit) and dropped the old myth.

Author: fmadore

mcpb/manifest.json

@@ -2,7 +2,7 @@
   "manifest_version": "0.3",
   "name": "iwac-mcp-server",
   "display_name": "Islam West Africa Collection (IWAC)",
-  "version": "0.8.0",
+  "version": "0.8.1",
   "description": "Read-only access to the Islam West Africa Collection via Hugging Face datasets.",
   "long_description": "Search and analyse the Islam West Africa Collection (IWAC): ~12,000 newspaper articles, 1,500 Islamic publications (searchable by keyword, subject, series, and table of contents), 4,700 index entries, plus audiovisual materials, archival documents, and academic references. Includes AI sentiment analysis (Gemini polarity/centrality) and per-article AI abstracts. All matching is accent- and case-insensitive.\n\n**No API key is required for the 20 core tools** (keyword search, filtering, statistics, item details). Two optional semantic-search tools use Gemini embeddings — covering all articles and the publication series with tables of contents — and need a free Google/Gemini API key; these are disabled by default.\n\nOn first use the server downloads ~250 MB of parquet data from Hugging Face into a local cache.",
   "author": {

mcpb/package.json

@@ -1,6 +1,6 @@
 {
   "name": "iwac-mcp-server-bundle",
-  "version": "0.8.0",
+  "version": "0.8.1",
   "description": "Node MCP server for the Islam West Africa Collection, packaged as a Claude Desktop extension (.mcpb).",
   "private": true,
   "type": "module",

mcpb/smoke-test.mjs

@@ -27,6 +27,19 @@ const serverVersion = client.getServerVersion()?.version;
 console.log(`server version: ${serverVersion}`);
 if (!serverVersion || serverVersion === "0.0.0-dev") fail("server version not injected from package.json");
 
+// Instructions parity (the ONLY guidance channel a skill-less client gets):
+// must reflect v0.8.x semantics and not the pre-v0.7 single-substring search myth.
+const instructions = client.getInstructions?.() ?? "";
+if (!instructions) {
+  fail("server handshake carried no instructions");
+} else {
+  if (instructions.includes("as one phrase returns little"))
+    fail("instructions still describe `search` as single-substring (multi-word now tokenizes/ANDs)");
+  for (const needle of ["valid_values", "mentioned in records from", "requested_limit"]) {
+    if (!instructions.includes(needle)) fail(`instructions missing v0.8 guidance: "${needle}"`);
+  }
+}
+
 const semanticOn = ["1", "true", "yes", "on"].includes(
   (process.env.IWAC_SEMANTIC_SEARCH_ENABLED ?? "").trim().toLowerCase(),
 );

mcpb/src/index.ts

@@ -22,15 +22,27 @@ const INSTRUCTIONS =
   "articles, Islamic publications, archival documents, audiovisual records, and academic " +
   "references on Islam and Muslim societies in Benin, Burkina Faso, Côte d'Ivoire, Niger, " +
   "Nigeria, and Togo.\n\n" +
-  "WORKFLOW: call `search` with ONE concept or name at a time, then `fetch` an id from the " +
-  "results to read the full text. Matching is substring-based, so 'pèlerinage' works but " +
-  "'pèlerinage Mecque' as one phrase returns little — search terms separately. When many items " +
-  "match, weigh result counts and AI abstracts before fetching full texts. Beyond search/fetch, " +
-  "finer tools exist (search_articles, search_publications, search_references, search_index, " +
-  "search_documents, plus get_* and list_*) with country, newspaper, subject, and date filters — " +
-  "prefer the `subject` filter over keywords for curated themes. All matching is accent- and " +
-  "case-insensitive; country filters take exact names (Benin, Burkina Faso, Côte d'Ivoire, " +
-  "Niger, Nigeria, Togo).\n\n" +
+  "WORKFLOW: start with `search` (a concept or name), then `fetch` an id from the results to read " +
+  "the full text. The unified `search` matches each word of a multi-word query independently — " +
+  "every word must appear somewhere in the item — so 'pèlerinage Mecque' narrows results rather " +
+  "than failing; prefer a single concept per call. The finer search_* tools' `keyword` filter " +
+  "instead does ONE literal substring match, so for those search one term at a time ('pèlerinage', " +
+  "then 'Mecque'). When many items match, weigh result counts and AI abstracts before fetching full " +
+  "texts. Beyond search/fetch, finer tools exist (search_articles, search_publications, " +
+  "search_references, search_index, search_documents, plus get_* and list_*) with country, " +
+  "newspaper, subject, and date filters — prefer the `subject` filter over keywords for curated " +
+  "themes. All matching is accent- and case-insensitive; country filters take exact names (Benin, " +
+  "Burkina Faso, Côte d'Ivoire, Niger, Nigeria, Togo).\n\n" +
+  "RESULTS & ERRORS: list/search tools return a pagination envelope — read `total_matches` to gauge " +
+  "scale without paging, and request a sane `limit` (an over-large one is capped visibly via " +
+  "`requested_limit` + `limit_warning`, never silently dropped). Enumerated filters (`country`, " +
+  "`polarity`, `centrality`, `index_type`) are validated: an invalid value returns {error, " +
+  "valid_values} to self-correct — an error to fix, not a finding — whereas a VALID value with 0 " +
+  "rows is a real absence (there is no Nigerian press, so country='Nigeria' on search_articles is " +
+  "genuinely empty). Free-text filters (newspaper, subject, author, reference_type, language) are " +
+  "NOT validated, so a typo there returns 0 silently — sanity-check them. On list_locations / " +
+  "list_persons, `country` means 'mentioned in records from that country' (not 'located there') and " +
+  "`frequency` is a collection-wide total; the response restates this in a `note`.\n\n" +
   "LANGUAGE: articles and documents are in FRENCH — query in French (laïcité, confrérie, " +
   "pèlerinage). Academic references are MULTILINGUAL — search both French AND English.\n\n" +
   "TRANSLITERATION: Arabic-Islamic terms appear in FRENCH transliteration — search the French " +