Metadata-Version: 2.4
Name: mcp-nav-shared
Version: 0.1.0
Summary: Shared helpers (LSP client, symbol resolution, formatting, workspace-root discovery) for the codenav/webnav MCP servers
Keywords: mcp,lsp,language-server,code-navigation
Author: Daniel Illescas Romero
Author-email: Daniel Illescas Romero <contact@daniel-ir.eu>
License-Expression: MIT
License-File: LICENSE
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Topic :: Software Development
Classifier: Typing :: Typed
Requires-Python: >=3.11
Project-URL: Homepage, https://github.com/illescasDaniel/SpaceMaker/tree/main/mcp-servers/mcp-nav-shared
Project-URL: Repository, https://github.com/illescasDaniel/SpaceMaker
Project-URL: Issues, https://github.com/illescasDaniel/SpaceMaker/issues
Description-Content-Type: text/markdown

# mcp-nav-shared

Shared helpers for the [`codenav-mcp`](https://pypi.org/project/codenav-mcp/)
and [`webnav-mcp`](https://pypi.org/project/webnav-mcp/) MCP servers. This
package is **not** an MCP server itself. It's installed automatically as a
dependency of both servers, so you don't need to install it yourself.

The API follows the servers' needs and may change between minor versions;
the servers pin a compatible range.

## What it provides

| Module | Role |
|--------|------|
| `mcp_nav_shared.lsp_client` | Async JSON-RPC/LSP subprocess client (`LspClient`): framing, request dispatch, document sync, file-change refresh, scratch documents |
| `mcp_nav_shared.resolve` | Name-based symbol resolution (`resolve_symbol`, dotted `Class.method`, ambiguity errors) |
| `mcp_nav_shared.format` | Location headers (`path:line:col`), snippets, compact references, diagnostics and outline lists |
| `mcp_nav_shared.workspace` | Workspace-root selection (`WorkspaceSelector`: env pin, client MCP roots in the same git repository, `CLAUDE_PROJECT_DIR`, working directory) |
| `mcp_nav_shared.errors` | Tool-facing error text (missing file, timeout, LSP errors, …) |
| `mcp_nav_shared.params` | `name`/`query` parameter aliases with a helpful hint when both are missing |
| `mcp_nav_shared.notices` | Notices appended to tool results (e.g. a config change restarted the language server, or the server's own code changed since it started) |
| `mcp_nav_shared.exclude` | Directory names every scan skips (`.git`, `node_modules`, `.venv`, …) |

## Development

Developed in the [SpaceMaker](https://github.com/illescasDaniel/SpaceMaker)
repository as a uv workspace member (`mcp-servers/mcp-nav-shared`). Design
notes: [docs/agent-tooling.md](https://github.com/illescasDaniel/SpaceMaker/blob/main/docs/agent-tooling.md).

## License

MIT. See [LICENSE](https://github.com/illescasDaniel/SpaceMaker/blob/main/mcp-servers/mcp-nav-shared/LICENSE).
