scholialang

Website · Spec · MCP · Python · Doug Fir Labs

scholialang-mcp

scholialang-mcp provides protocol tooling for Scholia:

• an MCP server exposing Scholia atlas lookup tools over stdio
• an MVP LSP server for editor navigation in .scholia traces
• provider stubs for Claude, Codex, Ollama, and OpenAI host adapters
• three release-ready plugins for the major coding harnesses, each with the same stdio MCP server, the same SQLite-backed local DAG, the same full v0.6 grammar validator, and shared storage:
  • plugins/codex/scholialang/ — Codex plugin
  • plugins/claude-code/scholialang/ — Claude Code plugin
  • plugins/ollama/scholialang/ — Ollama / local-model recipes for Continue.dev, Cline, open-webui, and generic stdio hosts

The repo is intentionally separate from scholialang, which contains the language model, parser, validator, and serializers. This package depends on scholialang>=0.6.0 and tracks scholialang-spec v0.6.0.

Install

For agent hosts, install the host plugin first. The plugins bundle the stdio MCP server and vendored validator snapshot, so normal Codex, Claude Code, and Ollama-backed usage does not require a Python package install or a curl installer.

Install the Codex plugin directly from the public GitHub marketplace:

codex plugin marketplace add https://github.com/dougfirlabs/scholialang-mcp.git
codex plugin add scholialang@scholialang-mcp
codex plugin list

Install the Claude Code plugin from the same marketplace:

claude plugin marketplace add https://github.com/dougfirlabs/scholialang-mcp.git --scope user
claude plugin install scholialang@scholialang-mcp --scope user

Install the Python package only when you want the standalone atlas MCP server, the LSP server, or local package development:

python -m pip install scholialang-mcp

For local development:

python -m venv .venv
. .venv/bin/activate
python -m pip install -e ".[dev]"
pytest

MCP Server

Run the MCP server against a workspace root:

python -m scholialang_mcp --repo-root /path/to/repo

The server speaks JSON-RPC over stdio and supports the MCP handshake: initialize, tools/list, and tools/call.

Tools:

• lookup_file_summary(path)
• lookup_directory_summary(path)
• lookup_feature_summary(feature)
• lookup_kb_summary(path)
• lookup_prd_summary(path)
• lookup_doc_summary(path)
• get_tree()
• regenerate(path)

License

The scholialang-mcp protocol tooling, plugins, and host integration code are dual-licensed under either MIT or Apache-2.0, at your option. See LICENSE, LICENSE-MIT, and LICENSE-APACHE.

The normative Scholia specification prose lives in scholialang-spec and is licensed separately under CC-BY-4.0.

Artifacts are read from a generic .scholia-atlas/ directory when present. Missing artifacts return structured not_generated_yet responses so host agents can fall back to ordinary file reads. Regeneration is host-specific in v0.6 and returns regenerate_unavailable unless a host adapter enables it.

Codex Atlas MCP Snippet

To expose the atlas lookup server globally to Codex, add the snippet printed by:

python -m scholialang_mcp codex-config --repo-root /path/to/repo

The command does not edit user config; it prints the [mcp_servers] section so installers and host-specific packages can apply it with explicit user consent.

Codex Trace MCP Fallback

The trace/DAG tools used by the Codex plugin (scholia_dag_start, scholia_dag_add_atom, scholia_codex_import_thread, and related tools) are served by the bundled Codex plugin server, not by the atlas lookup server above. Normally, install the Codex plugin from the GitHub marketplace. If a Codex thread loads the plugin metadata but does not expose working scholia_* tools, clone the repo and register the bundled server as a direct MCP fallback:

git clone https://github.com/dougfirlabs/scholialang-mcp.git
cd scholialang-mcp
codex mcp add scholialang \
  -- python3 "$PWD/plugins/codex/scholialang/scripts/scholialang_mcp_server.py"

Or print the equivalent ~/.codex/config.toml fallback snippet:

python -m scholialang_mcp codex-trace-config --repo-root /path/to/scholialang-mcp
# from an uninstalled source checkout:
PYTHONPATH=src python3 -m scholialang_mcp codex-trace-config --repo-root /path/to/scholialang-mcp

Harness Plugins