Periscope MCP server
Commit Nov 11, 2026Brokers MCP clients to a live Neovim configuration to access LSPs, formatters, linters, and DAP modules directly.
Also known as qompassai/periscope
- Stars
- 0
- Tools
- 16
- Downloads, 30 days
- —
- Latest version
- 1.0.0
- Last commit
- Nov 11, 2026
- License
- —
What is Periscope MCP?
Periscope brokers MCP clients to a live Neovim configuration to access LSPs, formatters, linters, and DAP modules directly. It exposes 16 tools, such as attention_alignment, attention_decide, attention_focus.
Summary generated from the project's README
About Periscope MCP server
Periscope acts as a bridge between MCP clients and a live Neovim instance, allowing AI agents to use your existing development environment. Instead of duplicating configurations, it connects to your actual LSP servers, formatters, linters, and DAP modules. This ensures the agent sees the exact same diagnostic and symbol information that you see in your editor. The server is a single Rust binary that communicates via stdio to the client and msgpack-RPC to Neovim.
Users can run the server in managed mode, where it spawns a headless Neovim instance in a specific workspace, or in attach mode to connect to an existing editor via a socket. It provides read-only intelligence through tools like get_definition, get_hover, and list_servers, alongside execution tools like run_format and run_lint. Notably, formatting tools return the modified text to the client without writing changes to the disk. It also includes a coordination system called the MATE protocol for agents to manage shared focus through attention tools.
What you can do with it
- 1Synchronize development intelligenceAn AI agent can query the same language servers and linter registries that your personal Neovim configuration uses.
- 2Coordinate multi-agent focusMultiple agents can use the attention board to publish their focus and decide how to handle overlapping tasks.
Written from the project's README. Every use case is checked against a quote from it.
Periscope MCP tools 16
Detected from the READMEattention_alignmentattention_decideattention_focusattention_publishbroker_statusget_definitionget_diagnosticsget_document_symbolsget_hoverget_referenceslist_daplist_formatters
Show all 16 toolsShow fewer tools
list_linterslist_serversrun_formatrun_lint
Automated checks
Ran Nov 14, 2026Full report →Not verified yet. A server needs a score of 80, no serious finding, and enough data for us to check. How checks work · What to fix for more points
- Source repository linked and reachableqompassai/periscope is public and reachablegithub.com/qompassai/periscope ↗Pass
- Package names this repository as its sourceNot checked
- Build provenance (Sigstore attestation)Not checked
- Open source license (OSI)No licenseFinding
- Commit or release in the last yearLast commit or release 2026-11-11github.com/qompassai/periscope ↗Pass
- OpenSSF ScorecardNot checked
- Package name not close to a popular packageNot checked
- No critical advisory in the package or its dependenciesNot checked
- No hidden instructions to the model16 tool descriptions and the README read; no override phrases, credential paths or hidden charactersPass
- Destructive tools are labelledNo tool named like delete, drop or execPass
- Remote endpoint answers the MCP handshakeNot checked
README
View on GitHubPeriscope
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.
| Tool | What it returns |
|---|---|
attention_alignment |
Alignment between your published focus and a partner agent's, measured only inside one saliency snapshot frame (Jaccard overlap, shared targets, shared top); refused across frames |
attention_decide |
Coordination decision against a partner agent's focus: parallel (no contention), serialize (same top target — the named holder proceeds, you defer), or reject (stale frame or invalid focus — re-snapshot, never guess) |
attention_focus |
A partner agent's currently advertised focus (ordered salient targets + the snapshot hash it was computed from) from the coordination board |
attention_publish |
Publish your focus to the coordination board: a focus document {agent_id, snapshot_hash, seq, targets[]} (at most 8 targets); the agent_id must equal your client identity and sequences must strictly advance |
broker_status |
mode, Neovim version, cwd, config root |
get_definition |
merged definition locations across attached clients |
get_diagnostics |
buffer diagnostics from vim.diagnostic (LSP + linter pipelines), with the producing source named on every entry |
get_document_symbols |
flattened symbol outline with containers |
get_hover |
hover text at a position |
get_references |
merged reference locations across attached clients |
list_dap |
DAP modules in the config tree plus adapters/configurations registered in the session |
list_formatters |
formatter modules in the config tree |
list_linters |
linter modules in the config tree (underscore-prefixed modules reported as internal) |
list_servers |
LSP servers configured in the tree, plus servers attached to any open buffer |
run_format |
Format a file with the config's formatter pipeline (require('formatters')); optional explicit formatter names and LSP mode (fallback / never / only); returns status, changed, the steps that ran, and the formatted text |
run_lint |
Lint a file with the config's linter runner (require('linters')); optional explicit linter names, otherwise the filetype's configured set; returns per-linter status, exit code, and diagnostics (each naming its linter in source) |
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>]
--workspacedefaults to the current directory and is where the managed editor starts.- Register it where you register MCP servers; in diver that is a
declared_serversentry inlua/ai/mcp/declared_servers.lua:
periscope = {
args = { '--workspace', '/path/to/project' },
cmd = '/home/phaedrus/.local/bin/periscope',
kind = 'stdio',
name = 'periscope',
source = 'local',
timeout = 5000,
tools = 'all',
},
Adapt cmd/args to the installation; drop the --workspace arg
entry to use the client's working directory, or point it at a
running editor with --attach <socket> instead.
Every wait and every list is bounded: editor attach 20 s, LSP
request phase 30 s (progress-gated polling), diagnostics settle 5 s,
connect deadline 10 s, VimEnter readiness 20 s. Result caps:
500 diagnostics locations per call, 1,000 document symbols (depth 6),
500 definition/reference locations, 4 MiB per MCP input line.
Errors from the editor are forwarded capped at 512 characters.
Tool failures are in-band MCP isError results, never protocol
errors.
stdio transport only — nothing listens on a network port. The managed editor's socket lives in a private temp path and is removed on shutdown; the broker reaps its child. No tool writes a file to disk, renames, or starts a debug session: formatting changes only the brokered editor's buffer and is returned as text, and the attention board is in-process memory that is dropped when the server exits.
- P2 (done): formatter and linter execution through the config's
own pipelines (
run_format,run_lint). - P3: write tools (rename, code actions, format-and-write) behind an explicit enable flag.
- P4: SCIP query tools over
index.scip(native Rust reader). - P5: DAP session driving.
Periscope MCP questions
What tools does Periscope MCP provide?
It exposes 16 tools, including attention_alignment, attention_decide, attention_focus, attention_publish, broker_status.
Does Periscope write changes to my files?
No, formatting is applied only to the brokered editor's buffer and returned as text; the file on disk is never written.
How does Periscope connect to my existing Neovim session?
You can use the Attach mode by providing the socket path of a running Neovim instance started with the --listen flag.
Is there any network exposure in Periscope?
No, it uses stdio transport only, meaning nothing listens on a network port.
What happens if an LSP server is slow to respond?
The tools poll inside the editor while servers report in-flight progress, allowing for real answers from slow servers like rust-analyzer.