Commands

`mcp_server.py`

The process your agent starts and talks to. You do not run it yourself; a client launches it. This page explains what it is, what it speaks, and how to test it by hand.

What it is

A small Model Context Protocol server over standard input and output, written with the standard library only. The client starts python3 /path/to/mcp_server.py as a child process and exchanges one JSON-RPC 2.0 message per line.

One process per session. That process remembers what it already sent and how many rules it activated; a new session starts fresh. See sessions.
One registration serves every project. The project is worked out from the file paths in each call, so you do not configure a server per project.
Logs go to stderr, prefixed [lore]. Standard output carries protocol messages only.

The protocol

Method	Reply
`initialize`	Echoes the client's `protocolVersion` (default `2024-11-05`), advertises the `tools` capability, names the server (`lore`, version `0.1.0`) and includes the instructions text (about 300 tokens; the wording follows the approval setting).
`tools/list`	The eight tools with their input schemas. See MCP tools.
`tools/call`	Runs a tool and returns its text. A tool that raises an error returns `isError: true` with the message; an unknown tool is a JSON-RPC error (`-32602`).
`ping`	An empty result.
notifications (no `id`)	No reply.
anything else	Error `-32601`, "method not found".
a line that is not JSON	Error `-32700`, "parse error", and the server carries on.

Only tools are offered: no resources and no prompts.

Testing it by hand

The quickest check that the server itself works, without any client:

printf '{"jsonrpc":"2.0","id":1,"method":"tools/list"}\n' | python3 mcp_server.py

A fuller conversation (initialize, then see the instructions):

printf '%s\n' \
  '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-03-26"}}' \
  '{"jsonrpc":"2.0","method":"notifications/initialized"}' \
  '{"jsonrpc":"2.0","id":2,"method":"tools/call","params":{"name":"get_rules","arguments":{"paths":["/home/you/projects/myapp/src/a.py"],"task":"add a thing"}}}' \
  | python3 mcp_server.py

Calls made this way count as real deliveries in usage.json, unlike the previews of review.py resolve.

The web UI has this check too Tools → Project → MCP check performs the handshake and lists the tools, the way a client would.

Starting it from a client

Every client needs the same three things: a command (python3 or the absolute Python), one argument (the absolute path to mcp_server.py) and nothing else: no environment variables are required. LORE_HOME moves the data folder and LORE_APPROVAL=manual forces manual mode for that process. Client-specific steps are in Connect your agent.

What happens inside a call

mcpserver/protocol.py parses the line and routes tools/call to the tool's handler. It knows nothing about Lore.
The handler in mcpserver/tools.py works out the project, validates its arguments and calls into the core (core.resolver, core.repository, discovery, reviews).
The four tools that depend on the session (get_rules, search_rules, record_feedback and propose_rules) receive the session object that create_server() made for this process.
The reply is plain text, wrapped in the protocol's content envelope.

Troubleshooting the connection

The client says the server failed to start. Run the command it was given by hand. A wrong path or a Python older than 3.10 shows up immediately.
It starts but no tools appear. Run the tools/list check above. If that works, the client's configuration is the problem (the wrong key or type: see the Copilot CLI and VS Code differences).
You changed Lore's code and nothing changed. The running server is the old process. Start a new agent session, or reconnect the server in the client.
You added or approved rules and want them now. No restart is needed: rules are read from disk on every call.