WebMCP Learning Search Tool

WebMCP Learning Search Tool

Status

Draft - awaiting review

Background

The Learn Project site currently hosts 19+ learnings documents under docs/learnings/. As this collection grows, manual navigation becomes inefficient for both humans and AI agents. WebMCP provides an elegant solution: expose a typed search tool that agents can call directly.

Problem

• Human visitors must browse/click through learnings to find relevant content
• AI agents would need to scrape DOM elements instead of querying structured content
• No filtering mechanism exists (by keyword, tag, date, or topic)

Goal

Implement a WebMCP tool search_learnings() that lets agents (and humans via agent interfaces) search learnings by keyword, returning structured results.

User Stories

US-1: Keyword Search

As a visiting AI agent, I want to search learnings by keyword so I can find relevant documentation without browsing.

Acceptance Criteria:

• Agent calls search_learnings(keyword) with a single search term
• Tool returns matching documents as structured JSON array
• Each result includes: title, slug, excerpt, date
• Search matches against title, description, and first 500 chars of content
• Results are sorted by relevance (title match > description match > content match)

US-2: Empty Result Handling

As an agent, I want clear feedback when no results match my query.

Acceptance Criteria:

• Tool returns empty array [] when no matches found
• Tool description notes this is normal for specific queries

Functional Requirements

ID	Requirement
FR-001	Tool name must be search_learnings
FR-002	Input schema: single string parameter keyword (required)
FR-003	Output must be JSON array of result objects
FR-004	Result object shape: { title, slug, date, excerpt }
FR-005	Search must be case-insensitive
FR-006	Maximum 10 results returned (top matches)
FR-007	Tool description ≤ 500 characters (WebMCP recommendation)
FR-008	readOnlyHint: true annotation

Design

Tool Registration (Imperative API)

const LEARNINGS_DATA = [
  // Astro collection data at build time
];

document.modelContext.registerTool({
  name: "search_learnings",
  description: "Search learnings and technical documentation by keyword. Returns title, date, and excerpt for matching documents. Returns empty array if no matches.",
  inputSchema: {
    type: "object",
    properties: {
      keyword: {
        type: "string",
        description: "Search term (e.g., 'astro', 'mcp', 'docker')"
      }
    },
    required: ["keyword"]
  },
  execute: async ({ keyword }) => {
    const matches = searchLearnings(keyword);
    return matches.slice(0, 10);
  },
  annotations: {
    readOnlyHint: true
  }
});

Data Source Options

Option	Pros	Cons	Recommendation
Build-time Astro collection data	Static, fast, no runtime deps	Data only current at build time	Preferred - fits static site
Client-side fetch of manifest.json	Runtime fresh	Requires build step to generate	If learnings updated frequently

Implementation Approach

1. Use Astro’s content collection to gather learnings at build time
2. Inject JSON array into page script via inline script or client:load module
3. Register WebMCP tool on learnings page only (contextual tool)

Performance Considerations

• Linear search across ~20 documents is negligible (< 1ms)
• No external API calls needed
• Tool only loads when learnings page is visited (ephemeral)

Non-Functional Requirements

ID	Requirement
NFR-001	Must not add more than 2KB to page bundle size
NFR-002	Must degrade gracefully: if WebMCP unavailable, page functions normally
NFR-003	No user-facing UI changes required (agent-only feature initially)

Test Plan

Test Case	Input	Expected
Basic keyword match	“astro”	Returns astro-related learnings
No match	“xyz123nonexistent”	Returns []
Special chars	“AI agents”	Matches documents about agents
Max results	“*” or “the”	≤ 10 results

Out of Scope (Now)

• Filtering by date range (future enhancement)
• Filtering by tags/categories (future enhancement)
• Human-visible search UI (future - could add for consistency)

Success Criteria

• Tool registered when docs/learnings/ pages are loaded
• Agent successfully calls tool and receives structured results
• Zero errors when WebMCP not available (graceful degradation)

Links

• WebMCP Imperative API Docs
• WebMCP Reference (internal)