Hister MCP Integration: Enabling AI Assistant Features Through Model Context Protocol

Hister integrates with the Model Context Protocol (MCP) by exposing a JSON-RPC 2.0 endpoint at /mcp that dispatches AI assistant requests to specialized tools—search, get_preview, and get_history—while treating all external data as untrusted content to prevent injection attacks.

The asciimoo/hister repository implements the Model Context Protocol to transform its personal search engine into an AI-accessible knowledge provider. By following the MCP specification, Hister allows compatible AI assistants to query indexed documents, generate page previews, and retrieve browsing history through a standardized interface. This integration centers on the server/mcp.go implementation, which handles protocol compliance and secure data serialization.

MCP Endpoint Registration in server/api.go

The integration begins in server/api.go at lines 1053-1065, where the HTTP router registers the /mcp route. Hister registers two handlers for this path:

• serveMCPGet – Returns HTTP 405 Method Not Allowed because the implementation does not support server-initiated event streams for GET requests.
• serveMCP – Handles POST requests carrying JSON-RPC 2.0 payloads, serving as the main entry point for AI assistant interactions.

This dual-registration ensures protocol compliance while preventing invalid transport methods.

Core MCP Request Processing Logic

The file server/mcp.go contains the full MCP implementation, beginning with a package comment explicitly stating its purpose: "Package server MCP endpoint implements the Model Context Protocol (MCP)". The core dispatcher resides in serveMCP, which parses incoming JSON-RPC requests and routes them via a switch statement on request.Method (lines 101-108).

The dispatcher calls specialized tool handlers:

• mcpToolSearch for full-text queries
• mcpToolGetPreview for URL metadata extraction
• mcpToolGetHistory for browsing history retrieval

Each handler returns a standardized result structure that the MCP specification requires.

Available MCP Tools for AI Assistants

Hister exposes three primary tools through its MCP interface, defined between lines 386-799 in server/mcp.go:

Search Tool (search)

Executes a full-text search against Hister's indexed documents. The tool returns results as an array of indexed_document records, each wrapped in the MCP structured result format. AI assistants can query the entire index without direct database access.

Get Preview Tool (get_preview)

Retrieves a specified URL, extracts the page title and description, and generates a safe HTML excerpt. The tool returns the data as an indexed_document record, allowing AI assistants to summarize web content before presenting it to users.

Get History Tool (get_history)

Supports two operational modes via the params.mode parameter:

• opened – Returns opened_history records containing URLs the user has recently browsed.
• indexed – Returns indexed_history records representing documents stored in the search index.

Both modes respect user privacy boundaries while providing contextual data to assistants.

Security Model and Untrusted Content Handling

Security is enforced through the untrusted records pattern. In server/mcp.go at lines 554-620, the newMCPStructuredResult constructor builds a mcpStructuredResult containing an array of untrusted records created via newMCPUntrustedRecord.

All content originating from the web or user-provided data is tagged with its source type. The normalizeUntrusted function (lines 567-681) performs sanitization by stripping invisible control characters to prevent injection attacks. This ensures AI assistants receive clearly labeled, sanitized data with explicit trust boundaries.

Practical MCP Usage Examples

Performing a Search

curl -X POST https://hister.example.com/mcp \
  -H "Content-Type: application/json" \
  -d '{
        "jsonrpc":"2.0",
        "id":1,
        "method":"search",
        "params":{"query":"golang tutorial"}
      }'

The response contains a structured_result with an array of untrusted_content records.

Requesting a Page Preview

curl -X POST https://hister.example.com/mcp \
  -H "Content-Type: application/json" \
  -d '{
        "jsonrpc":"2.0",
        "id":2,
        "method":"get_preview",
        "params":{"url":"https://golang.org/doc/"}
      }'

Returns an indexed_document with title, description, and safe HTML excerpt fields.

Fetching Recent History

curl -X POST https://hister.example.com/mcp \
  -H "Content-Type: application/json" \
  -d '{
        "jsonrpc":"2.0",
        "id":3,
        "method":"get_history",
        "params":{"mode":"opened"}
      }'

Returns opened_history records with URLs marked as untrusted.

MCP Testing in server/mcp_test.go

The server/mcp_test.go file contains the test suite validating the integration. Tests verify that:

• Search results are correctly normalized and marked as untrusted.
• The get_preview tool returns rendered HTML while preserving metadata security.
• get_history respects the requested mode parameter (opened vs. indexed).
• The endpoint correctly advertises the MCP protocol version defined in server/server.go.

These tests ensure that Hister maintains protocol compliance while preserving security guarantees across AI assistant interactions.

Summary

• Hister exposes an MCP endpoint at /mcp using JSON-RPC 2.0 transport, registered in server/api.go at lines 1053-1065.
• The core implementation in server/mcp.go dispatches requests to three tools: search, get_preview, and get_history.
• All external data is wrapped in untrusted records via newMCPUntrustedRecord and sanitized by normalizeUntrusted to prevent injection.
• The endpoint rejects GET requests (returning 405) because server-initiated streams are not supported.
• Comprehensive tests in server/mcp_test.go validate security, protocol compliance, and tool functionality.

Frequently Asked Questions

What is the Model Context Protocol (MCP) endpoint URL in Hister?

The MCP endpoint is available at /mcp on the Hister server. According to the source code in server/api.go, this path accepts POST requests containing JSON-RPC 2.0 payloads and rejects GET requests with a 405 status code.

Which MCP tools does Hister expose for AI assistants?

Hister exposes three primary tools: search for full-text indexing, get_preview for URL metadata extraction, and get_history for retrieving browsing history in either opened or indexed modes. These are implemented in server/mcp.go between lines 386-799.

How does Hister prevent injection attacks in MCP responses?

All content retrieved from external sources is treated as untrusted. The normalizeUntrusted function in server/mcp.go (lines 567-681) strips invisible control characters from responses, and the newMCPUntrustedRecord constructor explicitly tags data with its source type, creating a clear security boundary for AI assistants.

Why does the Hister MCP endpoint reject GET requests?

The serveMCPGet handler returns Method Not Allowed because the MCP implementation in Hister does not support server-initiated event streams. The protocol requires client-initiated POST requests with JSON-RPC 2.0 payloads to the /mcp endpoint.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}