Periscope

Periscope

An MCP server that brokers to a real Neovim running your actual diver config, so MCP clients (agents) query the same language servers, formatter registry, linter registry, and DAP module tree you edit with — one configuration source of truth, no duplicate servers, no translated config files.

Periscope is a single Rust binary. It speaks MCP over stdio (NDJSON JSON-RPC) to the client and msgpack-RPC to Neovim.

How it runs

• Managed mode (default): spawns its own nvim --headless --listen <tmp socket> with cwd set to the workspace. Your config loads exactly as it does for you; the broker never touches your interactive editor. Project-local config execution is refused (--cmd "set noexrc").
• Attach mode (--attach <socket>): connects to a Neovim you already have running (anything started with --listen). The broker never signals or closes an editor it did not spawn.

Tools are small Lua programs executed inside the editor via nvim_exec_lua. They use native APIs only (vim.lsp, vim.diagnostic, runtime files) and inherit every per-server setting in your lsp/*.lua files — including deliberate choices like rust-analyzer's native diagnostics being disabled in favour of bacon-ls.

Tools

Read-only intelligence (broker_status, get_*, list_*) plus two execution tools (run_format, run_lint) that run the config's own pipelines inside the editor. Formatting is applied to the brokered editor's buffer and returned as text — the file on disk is never written (written is always false; write-to-disk tools are a later phase behind an explicit enable flag). Linting only reads. Four attention_* tools serve a joint-attention coordination board held in the server process (the MATE protocol, vendored from phlow-attention): agents publish an ordered focus, read each other's, and ask for an alignment score or a coordination decision. The board never touches the editor or the filesystem, and a publish is bound to the identity the client presented at initialize.

Positions are 0-based; character counts UTF-16 code units (the LSP convention). LSP request tools poll inside the editor while servers report in-flight progress, so a cold rust-analyzer returns its real answer (~10 s on a small project) instead of a fast, empty one.

periscope [--workspace <dir>] [--attach <socket>] [--nvim-bin <path>]

periscope = {
    args = { '--workspace', '/path/to/project' },
    cmd = '/home/phaedrus/.local/bin/periscope',
    kind = 'stdio',
    name = 'periscope',
    source = 'local',
    timeout = 5000,
    tools = 'all',
},