MoContext Human Guide

Use this page to help an AI client remember and use MoContext. Copy the short bootstrap into persistent custom instructions, or copy the longer session prompt into a single chat when you want to steer that session.

• Custom instructions: paste once into Codex or another AI client settings box.
• Session prompt: paste into a chat when custom instructions are not configured or you want a stronger reminder.
• Appendix: read the technical sections below when you want to understand how MoContext works.

Appendix: how MoContext works

Audience: Technical users and admins. Covers architecture, data flows, HTTP endpoints, and MCP tools. For internal codebase detail (service layer, file map, WinForms threading, startup sequence) see MoContext_Codebase.html.

1. What Is MoContext?

MoContext is a single-executable, local-loopback server that gives AI agents (and developers) two things: grounded source retrieval from the MoSearch full-text index, and a lightweight activity journal for recording what the AI worked on. It exposes the same surface over two parallel entry points — a classic REST HTTP API and a Model Context Protocol (MCP) endpoint — and ships a WinForms system-tray dashboard for monitoring.

2. System Overview

MoContext sits between AI clients and the local filesystem. MoSearch's indexer is a fully separate process that writes MoSl.db; MoContext only reads it. The MoSearch Search UI is the original user-facing query tool — it reads the same MoSl.db and opens source files directly; HTTP and MCP are two new avenues into that same underlying index.

3. HTTP vs MCP — Parallel Entry Points

This is the most important structural point. MCP is not layered on top of HTTP. Both entry points call the same service singletons through ASP.NET Core DI. The MCP SDK registers a handler at /mcp alongside the /v1/ route handlers — they are peers, not stacked.

4. Database Architecture

MoContext works with two SQLite databases. They typically live in the same %LOCALAPPDATA%\Meauxsoft\Mo-Search<ver>\ AppData folder but are structurally independent. MoSearch owns and writes MoSl.db; MoContext only reads it. MoContext owns and reads/writes MoContext.db.

5. HTTP Endpoints GET/POST /v1/...

Read (no auth required)

  55:     private readonly JwtSecurityTokenHandler _handler;
  56:     private TokenValidationParameters _params;
› 57:     public bool ValidateJwtToken(string token) {
  58:         var r = _handler.ValidateToken(token, _params, out _);
  59:         return r.IsValid;
  60:     }

  81:     [HttpPost("login")]
  82:     public IActionResult Login([FromBody] LoginRequest req) {
› 83:         if (!_auth.ValidateJwtToken(req.Token)) return Unauthorized();
  84:         return Ok(GenerateSession(req));
  85:     }

  53:     private TokenValidationParameters _params;
  54:
  55:     public AuthService(IOptions<AuthOptions> opts) {
  56:         _params = BuildParams(opts.Value);
› 57:         _handler = new JwtSecurityTokenHandler();
  58:     }
  59:
  60:     public bool ValidateJwtToken(string token) {
  61:         return _handler.ValidateToken(token, _params, out _).IsValid;

Write (optional Bearer auth)

Every /v1/ request records an api_call event (fire-and-forget). Every /mcp request records an mcp_transport event. Individual MCP tools also record mcp_tool_call events.

6. MCP Tools (auto-discovered from MoContextMcpTools.cs)

MoContext currently exposes 22 MCP tools. Important first-call and context-file tools include get_server_summary, get_usage_guide, get_diagnostics, get_context_paths, list_context_files, read_context_file, and write_memory_file. The table below summarizes the core retrieval and activity tools with examples; MCP clients should trust tools/list for the exact current schema.

Read / retrieval tools

  55:     private readonly JwtSecurityTokenHandler _handler;
  56:     private TokenValidationParameters _params;
› 57:     public bool ValidateJwtToken(string token) {
  58:         var r = _handler.ValidateToken(token, _params, out _);
  59:         return r.IsValid;
  60:     }

  10:     // Shared validation params used by AuthService
  11:     public static class TokenHelper {
› 12:         public static bool ValidateJwtToken(string t, string secret) =>
  13:             new JwtSecurityTokenHandler().CanReadToken(t);
  14:     }

  53:     private TokenValidationParameters _params;
  54:
  55:     public AuthService(IOptions<AuthOptions> opts) {
  56:         _params = BuildParams(opts.Value);
› 57:         _handler = new JwtSecurityTokenHandler();
  58:     }
  59:
  60:     public bool ValidateJwtToken(string token) {
  61:         return _handler.ValidateToken(token, _params, out _).IsValid;

Continuity / write tools

MCP uses ModelContextProtocol.AspNetCore 1.1.0. Transport: Streamable HTTP with stateful sessions (Mcp-Session-Id header). Protocol version: 2025-11-25. Tools are discovered via WithToolsFromAssembly() — all [McpServerTool] methods in the assembly are registered automatically.

7. Runtime File System Layout

Section 11 (Startup Sequence) — moved to MoContext_Codebase.html.

Generated from MoContext source — MoContext\src\MoContext.Server\docs\MoContext_Overview.html