Skip to content
Uvilo OS
archived Visibility internal Owner erik@uvilo.com Approver _ Created _ Updated _

Typesense Plan — Phase 2: MCP Server

This phase builds the MCP server for agents. It depends on the Typesense instance and indexed data from Phase 1.

Prerequisites

  • Phase 1 complete: Typesense running on Railway, uvilo collection populated
  • Search-only API key created in Typesense

Tasks

  • Create search-only API key in Typesense

    • Use the admin key to create a scoped key: POST /keys with actions: ["documents:search"], collections: ["uvilo"]
    • Store the key as TYPESENSE_SEARCH_KEY in Railway env vars on the MCP service

  • Build the MCP server (typesense-mcp)

    • Initialize Node.js project with @modelcontextprotocol/sdk
    • Implement search_knowledge tool
      • Parameters: query (string, required), department (optional string), project (optional string), type (optional string), source (optional string: repo or website), status (optional string), visibility (optional string), owner (optional string), limit (optional number, default 5)
      • Uses Typesense multi_search API with hybrid search (keyword + semantic)
      • Builds filter_by string from optional params
      • Returns array of {path, title, summary, snippet, score}
    • Implement get_file_summary tool
      • Parameters: path (string, required)
      • Queries Typesense by path field and returns the summary field
      • No filesystem access needed — summary is stored in Typesense at index time
    • Transport: SSE (streamable HTTP) on port 3000
    • Add error handling for Typesense connection failures
    • Add input validation for query parameters

  • Deploy MCP server to Railway

    • Write Dockerfile for the MCP server (Node.js runtime)
    • Deploy as a Railway service in the same project
    • Set environment variables: TYPESENSE_HOST, TYPESENSE_SEARCH_KEY, TYPESENSE_PORT
    • Enable internal networking (no public domain)
    • Verify health: curl http://typesense-mcp.railway.internal:3000/health

  • Add MCP server to LibreChat config

    • Add typesense-mcp entry to Forge/Configs/LibreChat_Service/librechat.yaml under mcpServers
    • Use SSE transport with Railway internal URL
    • Add server instructions describing the two tools
    • Deploy config via /deploy-config skill
    • Start a new conversation and verify search_knowledge and get_file_summary appear in tool list

  • Add Knowledge doc for Typesense

    • Create Forge/Knowledge/Tools/Typesense.md with connection details, API usage, quirks

  • Add sidebar entries for Phase 2 Plan page

    • Add to .internal/astro.config.mjs

  • Commit and push to dev

Verification

  • MCP server responds to health check
  • search_knowledge tool returns relevant results for “memory architecture”
  • search_knowledge with department=Forge filters correctly
  • search_knowledge with project=TypeSense filters correctly
  • get_file_summary returns AI-generated summary for a known file
  • LibreChat conversation shows both tools available