Navegador

navegador / docs / api / mcp.md
Source Blame History 400 lines
ce0374a… lmata 1 # MCP Server API
ce0374a… lmata 2
ce0374a… lmata 3 Navegador exposes all context-loading commands as an MCP server. The server is created with `create_mcp_server()` and speaks the [Model Context Protocol](https://modelcontextprotocol.io) over stdio.
ce0374a… lmata 4
ce0374a… lmata 5 ```python
ce0374a… lmata 6 from navegador.mcp import create_mcp_server
ce0374a… lmata 7 ```
ce0374a… lmata 8
ce0374a… lmata 9 ---
ce0374a… lmata 10
ce0374a… lmata 11 ## create_mcp_server
ce0374a… lmata 12
ce0374a… lmata 13 ```python
ce0374a… lmata 14 def create_mcp_server(
ce0374a… lmata 15 store: GraphStore | None = None,
ce0374a… lmata 16 db_path: str = "",
89816aa… lmata 17 read_only: bool = False,
89816aa… lmata 18 max_query_complexity: int = 0,
ce0374a… lmata 19 ) -> MCPServer: ...
ce0374a… lmata 20 ```
ce0374a… lmata 21
ce0374a… lmata 22 Creates and returns an MCP server instance. If `store` is not provided, opens a `GraphStore.sqlite()` at `db_path` (or `NAVEGADOR_DB` env var, or `./navegador.db`).
ce0374a… lmata 23
89816aa… lmata 24 - `read_only`: when `True`, disables the `ingest` tool and restricts the `query` tool to `MATCH`/`RETURN` only. Corresponds to `navegador mcp --read-only`.
89816aa… lmata 25 - `max_query_complexity`: if non-zero, rejects Cypher queries whose estimated complexity exceeds this value. Prevents runaway traversals in multi-agent environments.
89816aa… lmata 26
89816aa… lmata 27 The CLI command `navegador mcp [--db path] [--read-only]` calls this function and runs the server loop.
ce0374a… lmata 28
ce0374a… lmata 29 ### Usage
ce0374a… lmata 30
ce0374a… lmata 31 ```python
ce0374a… lmata 32 from navegador.graph import GraphStore
ce0374a… lmata 33 from navegador.mcp import create_mcp_server
ce0374a… lmata 34
ce0374a… lmata 35 store = GraphStore.sqlite(".navegador/navegador.db")
ce0374a… lmata 36 server = create_mcp_server(store=store)
ce0374a… lmata 37 server.run() # blocks; serves over stdio
ce0374a… lmata 38 ```
ce0374a… lmata 39
ce0374a… lmata 40 To embed in a larger MCP server:
ce0374a… lmata 41
ce0374a… lmata 42 ```python
ce0374a… lmata 43 server = create_mcp_server(db_path=".navegador/navegador.db")
ce0374a… lmata 44 # register additional tools on server before running
ce0374a… lmata 45 server.run()
ce0374a… lmata 46 ```
ce0374a… lmata 47
ce0374a… lmata 48 ---
ce0374a… lmata 49
ce0374a… lmata 50 ## Available MCP tools
ce0374a… lmata 51
89816aa… lmata 52 All tools accept JSON input and return JSON output. There are 11 tools in total.
ce0374a… lmata 53
ce0374a… lmata 54 ---
ce0374a… lmata 55
ce0374a… lmata 56 ### `ingest`
ce0374a… lmata 57
ce0374a… lmata 58 Ingest a repository or file into the graph.
ce0374a… lmata 59
ce0374a… lmata 60 **Input schema:**
ce0374a… lmata 61 ```json
ce0374a… lmata 62 {
ce0374a… lmata 63 "type": "object",
ce0374a… lmata 64 "properties": {
ce0374a… lmata 65 "path": {
ce0374a… lmata 66 "type": "string",
ce0374a… lmata 67 "description": "Path to the repo or file to ingest"
ce0374a… lmata 68 },
ce0374a… lmata 69 "clear": {
ce0374a… lmata 70 "type": "boolean",
ce0374a… lmata 71 "description": "Wipe the graph before ingesting",
ce0374a… lmata 72 "default": false
ce0374a… lmata 73 }
ce0374a… lmata 74 },
ce0374a… lmata 75 "required": ["path"]
ce0374a… lmata 76 }
ce0374a… lmata 77 ```
ce0374a… lmata 78
ce0374a… lmata 79 **Output:** `IngestionResult` serialized to JSON.
ce0374a… lmata 80
ce0374a… lmata 81 ---
ce0374a… lmata 82
ce0374a… lmata 83 ### `context`
ce0374a… lmata 84
ce0374a… lmata 85 Return the full context bundle for a source file.
ce0374a… lmata 86
ce0374a… lmata 87 **Input schema:**
ce0374a… lmata 88 ```json
ce0374a… lmata 89 {
ce0374a… lmata 90 "type": "object",
ce0374a… lmata 91 "properties": {
ce0374a… lmata 92 "file": {
ce0374a… lmata 93 "type": "string",
ce0374a… lmata 94 "description": "Path to the source file"
ce0374a… lmata 95 },
ce0374a… lmata 96 "format": {
ce0374a… lmata 97 "type": "string",
ce0374a… lmata 98 "enum": ["json", "markdown"],
ce0374a… lmata 99 "default": "json"
ce0374a… lmata 100 }
ce0374a… lmata 101 },
ce0374a… lmata 102 "required": ["file"]
ce0374a… lmata 103 }
ce0374a… lmata 104 ```
ce0374a… lmata 105
ce0374a… lmata 106 **Output:** `ContextBundle` as JSON or markdown string.
ce0374a… lmata 107
ce0374a… lmata 108 ---
ce0374a… lmata 109
ce0374a… lmata 110 ### `function`
ce0374a… lmata 111
ce0374a… lmata 112 Return a function's context bundle including callers, callees, and decorators.
ce0374a… lmata 113
ce0374a… lmata 114 **Input schema:**
ce0374a… lmata 115 ```json
ce0374a… lmata 116 {
ce0374a… lmata 117 "type": "object",
ce0374a… lmata 118 "properties": {
ce0374a… lmata 119 "name": {
ce0374a… lmata 120 "type": "string",
ce0374a… lmata 121 "description": "Function name"
ce0374a… lmata 122 },
ce0374a… lmata 123 "file": {
ce0374a… lmata 124 "type": "string",
ce0374a… lmata 125 "description": "Optional file path to disambiguate"
ce0374a… lmata 126 },
ce0374a… lmata 127 "depth": {
ce0374a… lmata 128 "type": "integer",
ce0374a… lmata 129 "description": "Call graph traversal depth",
ce0374a… lmata 130 "default": 1
ce0374a… lmata 131 }
ce0374a… lmata 132 },
ce0374a… lmata 133 "required": ["name"]
ce0374a… lmata 134 }
ce0374a… lmata 135 ```
ce0374a… lmata 136
ce0374a… lmata 137 **Output:** `ContextBundle` as JSON.
ce0374a… lmata 138
ce0374a… lmata 139 ---
ce0374a… lmata 140
ce0374a… lmata 141 ### `class`
ce0374a… lmata 142
ce0374a… lmata 143 Return a class context bundle including hierarchy, methods, and references.
ce0374a… lmata 144
ce0374a… lmata 145 **Input schema:**
ce0374a… lmata 146 ```json
ce0374a… lmata 147 {
ce0374a… lmata 148 "type": "object",
ce0374a… lmata 149 "properties": {
ce0374a… lmata 150 "name": {
ce0374a… lmata 151 "type": "string",
ce0374a… lmata 152 "description": "Class name"
ce0374a… lmata 153 },
ce0374a… lmata 154 "file": {
ce0374a… lmata 155 "type": "string",
ce0374a… lmata 156 "description": "Optional file path to disambiguate"
ce0374a… lmata 157 }
ce0374a… lmata 158 },
ce0374a… lmata 159 "required": ["name"]
ce0374a… lmata 160 }
ce0374a… lmata 161 ```
ce0374a… lmata 162
ce0374a… lmata 163 **Output:** `ContextBundle` as JSON.
ce0374a… lmata 164
ce0374a… lmata 165 ---
ce0374a… lmata 166
ce0374a… lmata 167 ### `explain`
ce0374a… lmata 168
ce0374a… lmata 169 Universal lookup: explain any node (function, class, file, concept, rule, decision) by name.
ce0374a… lmata 170
ce0374a… lmata 171 **Input schema:**
ce0374a… lmata 172 ```json
ce0374a… lmata 173 {
ce0374a… lmata 174 "type": "object",
ce0374a… lmata 175 "properties": {
ce0374a… lmata 176 "name": {
ce0374a… lmata 177 "type": "string",
ce0374a… lmata 178 "description": "Node name to explain"
ce0374a… lmata 179 },
ce0374a… lmata 180 "file": {
ce0374a… lmata 181 "type": "string",
ce0374a… lmata 182 "description": "Optional file path to disambiguate code nodes"
ce0374a… lmata 183 }
ce0374a… lmata 184 },
ce0374a… lmata 185 "required": ["name"]
ce0374a… lmata 186 }
ce0374a… lmata 187 ```
ce0374a… lmata 188
ce0374a… lmata 189 **Output:** `ContextBundle` as JSON.
ce0374a… lmata 190
ce0374a… lmata 191 ---
ce0374a… lmata 192
ce0374a… lmata 193 ### `search`
ce0374a… lmata 194
ce0374a… lmata 195 Search the graph by text query.
ce0374a… lmata 196
ce0374a… lmata 197 **Input schema:**
ce0374a… lmata 198 ```json
ce0374a… lmata 199 {
ce0374a… lmata 200 "type": "object",
ce0374a… lmata 201 "properties": {
ce0374a… lmata 202 "query": {
ce0374a… lmata 203 "type": "string",
ce0374a… lmata 204 "description": "Search query"
ce0374a… lmata 205 },
ce0374a… lmata 206 "all": {
ce0374a… lmata 207 "type": "boolean",
ce0374a… lmata 208 "description": "Search all layers including knowledge layer",
ce0374a… lmata 209 "default": false
ce0374a… lmata 210 },
ce0374a… lmata 211 "docs": {
ce0374a… lmata 212 "type": "boolean",
ce0374a… lmata 213 "description": "Search docstrings and wiki content only",
ce0374a… lmata 214 "default": false
ce0374a… lmata 215 },
ce0374a… lmata 216 "limit": {
ce0374a… lmata 217 "type": "integer",
ce0374a… lmata 218 "description": "Maximum results to return",
ce0374a… lmata 219 "default": 20
ce0374a… lmata 220 }
ce0374a… lmata 221 },
ce0374a… lmata 222 "required": ["query"]
ce0374a… lmata 223 }
ce0374a… lmata 224 ```
ce0374a… lmata 225
ce0374a… lmata 226 **Output:** Array of `ContextNode` objects as JSON.
ce0374a… lmata 227
ce0374a… lmata 228 ---
ce0374a… lmata 229
ce0374a… lmata 230 ### `query`
ce0374a… lmata 231
ce0374a… lmata 232 Execute a raw Cypher query against the graph.
ce0374a… lmata 233
ce0374a… lmata 234 **Input schema:**
ce0374a… lmata 235 ```json
ce0374a… lmata 236 {
ce0374a… lmata 237 "type": "object",
ce0374a… lmata 238 "properties": {
ce0374a… lmata 239 "cypher": {
ce0374a… lmata 240 "type": "string",
ce0374a… lmata 241 "description": "Cypher query string"
ce0374a… lmata 242 },
ce0374a… lmata 243 "params": {
ce0374a… lmata 244 "type": "object",
ce0374a… lmata 245 "description": "Optional query parameters",
ce0374a… lmata 246 "default": {}
ce0374a… lmata 247 }
ce0374a… lmata 248 },
ce0374a… lmata 249 "required": ["cypher"]
ce0374a… lmata 250 }
ce0374a… lmata 251 ```
ce0374a… lmata 252
ce0374a… lmata 253 **Output:** Array of result rows as JSON.
ce0374a… lmata 254
ce0374a… lmata 255 !!! warning
89816aa… lmata 256 This tool executes writes as well as reads. Agents should use read-only queries (`MATCH` / `RETURN`) unless explicitly performing graph updates. Use `--read-only` mode or `read_only=True` in `create_mcp_server()` to enforce this at the server level.
89816aa… lmata 257
89816aa… lmata 258 ---
89816aa… lmata 259
89816aa… lmata 260 ### `get_rationale`
89816aa… lmata 261
89816aa… lmata 262 Return the rationale, decisions, and rules that govern a named code node.
89816aa… lmata 263
89816aa… lmata 264 **Input schema:**
89816aa… lmata 265 ```json
89816aa… lmata 266 {
89816aa… lmata 267 "type": "object",
89816aa… lmata 268 "properties": {
89816aa… lmata 269 "name": {
89816aa… lmata 270 "type": "string",
89816aa… lmata 271 "description": "Function, class, or file name"
89816aa… lmata 272 },
89816aa… lmata 273 "file": {
89816aa… lmata 274 "type": "string",
89816aa… lmata 275 "description": "Optional file path to disambiguate"
89816aa… lmata 276 }
89816aa… lmata 277 },
89816aa… lmata 278 "required": ["name"]
89816aa… lmata 279 }
89816aa… lmata 280 ```
89816aa… lmata 281
89816aa… lmata 282 **Output:** Array of `Decision` and `Rule` nodes with `rationale` fields, as JSON.
89816aa… lmata 283
89816aa… lmata 284 ---
89816aa… lmata 285
89816aa… lmata 286 ### `find_owners`
89816aa… lmata 287
89816aa… lmata 288 Return the people and domains that own a code node, based on CODEOWNERS, annotation, and domain membership.
89816aa… lmata 289
89816aa… lmata 290 **Input schema:**
89816aa… lmata 291 ```json
89816aa… lmata 292 {
89816aa… lmata 293 "type": "object",
89816aa… lmata 294 "properties": {
89816aa… lmata 295 "name": {
89816aa… lmata 296 "type": "string",
89816aa… lmata 297 "description": "Function, class, or file name"
89816aa… lmata 298 },
89816aa… lmata 299 "file": {
89816aa… lmata 300 "type": "string",
89816aa… lmata 301 "description": "Optional file path"
89816aa… lmata 302 }
89816aa… lmata 303 },
89816aa… lmata 304 "required": ["name"]
89816aa… lmata 305 }
89816aa… lmata 306 ```
89816aa… lmata 307
89816aa… lmata 308 **Output:** Array of `Person` and `Domain` nodes as JSON.
89816aa… lmata 309
89816aa… lmata 310 ---
89816aa… lmata 311
89816aa… lmata 312 ### `search_knowledge`
89816aa… lmata 313
89816aa… lmata 314 Search the knowledge layer only (concepts, rules, decisions, wiki pages, domains).
89816aa… lmata 315
89816aa… lmata 316 **Input schema:**
89816aa… lmata 317 ```json
89816aa… lmata 318 {
89816aa… lmata 319 "type": "object",
89816aa… lmata 320 "properties": {
89816aa… lmata 321 "query": {
89816aa… lmata 322 "type": "string",
89816aa… lmata 323 "description": "Search query"
89816aa… lmata 324 },
89816aa… lmata 325 "limit": {
89816aa… lmata 326 "type": "integer",
89816aa… lmata 327 "description": "Maximum results to return",
89816aa… lmata 328 "default": 20
89816aa… lmata 329 }
89816aa… lmata 330 },
89816aa… lmata 331 "required": ["query"]
89816aa… lmata 332 }
89816aa… lmata 333 ```
89816aa… lmata 334
89816aa… lmata 335 **Output:** Array of knowledge layer `ContextNode` objects as JSON.
89816aa… lmata 336
89816aa… lmata 337 ---
89816aa… lmata 338
89816aa… lmata 339 ### `blast_radius`
89816aa… lmata 340
89816aa… lmata 341 Return all code nodes transitively reachable from a given node via CALLS, IMPORTS, and INHERITS edges — the set of things that could break if this node changes.
89816aa… lmata 342
89816aa… lmata 343 **Input schema:**
89816aa… lmata 344 ```json
89816aa… lmata 345 {
89816aa… lmata 346 "type": "object",
89816aa… lmata 347 "properties": {
89816aa… lmata 348 "name": {
89816aa… lmata 349 "type": "string",
89816aa… lmata 350 "description": "Starting node name"
89816aa… lmata 351 },
89816aa… lmata 352 "file": {
89816aa… lmata 353 "type": "string",
89816aa… lmata 354 "description": "Optional file path to disambiguate"
89816aa… lmata 355 },
89816aa… lmata 356 "depth": {
89816aa… lmata 357 "type": "integer",
89816aa… lmata 358 "description": "Maximum traversal depth",
89816aa… lmata 359 "default": 3
89816aa… lmata 360 }
89816aa… lmata 361 },
89816aa… lmata 362 "required": ["name"]
89816aa… lmata 363 }
89816aa… lmata 364 ```
89816aa… lmata 365
89816aa… lmata 366 **Output:** Array of `ContextNode` objects ordered by distance from the starting node.
89816aa… lmata 367
89816aa… lmata 368 ---
89816aa… lmata 369
89816aa… lmata 370 ## Security
89816aa… lmata 371
89816aa… lmata 372 ### Read-only mode
89816aa… lmata 373
89816aa… lmata 374 Start the server in read-only mode to prevent agents from modifying the graph:
89816aa… lmata 375
89816aa… lmata 376 ```bash
89816aa… lmata 377 navegador mcp --read-only
89816aa… lmata 378 ```
89816aa… lmata 379
89816aa… lmata 380 In read-only mode:
89816aa… lmata 381 - The `ingest` tool is disabled (returns an error if called)
89816aa… lmata 382 - The `query` tool validates that queries contain only `MATCH`, `RETURN`, `WITH`, `WHERE`, `ORDER BY`, `LIMIT`, and `SKIP` clauses
89816aa… lmata 383 - Write Cypher keywords (`CREATE`, `MERGE`, `SET`, `DELETE`, `DETACH`) are rejected
89816aa… lmata 384
89816aa… lmata 385 ### Query complexity limits
89816aa… lmata 386
89816aa… lmata 387 Set a maximum query complexity to prevent runaway traversals:
89816aa… lmata 388
89816aa… lmata 389 ```bash
89816aa… lmata 390 navegador mcp --max-query-complexity 100
89816aa… lmata 391 ```
89816aa… lmata 392
89816aa… lmata 393 Or in `.navegador/config.toml`:
89816aa… lmata 394
89816aa… lmata 395 ```toml
89816aa… lmata 396 [mcp]
89816aa… lmata 397 max_query_complexity = 100
89816aa… lmata 398 ```
89816aa… lmata 399
89816aa… lmata 400 Queries that exceed the complexity threshold return an error rather than executing.

Keyboard Shortcuts

Open search /
Next entry (timeline) j
Previous entry (timeline) k
Open focused entry Enter
Show this help ?
Toggle theme Top nav button