mcpserver

📄Description

mcpserver starts a stdio MCP server exposing Nelson-aware tools.

The transport uses standard input and standard output. MCP JSON-RPC messages are the only data written to standard output; diagnostic messages are written to standard error.

The default display mode is adv-cli. It supports graphical commands used by create_nelson_plot while keeping the MCP transport on standard output. Use cli for text-only sessions. Use gui when a visible graphical Nelson session is desired while the server still runs from nelson-adv-cli.

Available tools are detect_nelson_modules, check_nelson_code, lint_nelson_code, check_nelson_format, evaluate_nelson_code, run_nelson_file, run_nelson_test_file, format_nelson_file, get_nelson_help, find_nelson_symbol, get_nelson_function_info, get_nelson_workspace, get_nelson_version, and create_nelson_plot.

File-based tools resolve relative paths from the configured workspace root and refuse paths outside that root. The default workspace root is nelsonroot.

Tool calls return both text content and structured content with success, output, error, image, and duration fields.

Long output and error fields are bounded by --max-output-characters. Structured content includes output_truncated and error_truncated flags.

Some tools also return typed metadata in the structured data field, for example module lists, test summary counts, version information, and PNG image metadata.

The server also exposes local read-only resources under guidelines:// and reusable prompts such as nelson-code-review, nelson-test-author, and nelson-plot-agent.

Ollama can provide the local language model for an MCP-capable agent. In that setup, Ollama runs the model, the agent speaks MCP, and mcpserver exposes Nelson tools to the agent.

The JSON-RPC transport validates protocol version 2.0, rejects invalid requests, and supports batch requests.

💡Examples

Start the server from an MCP client.

nelson-adv-cli --quiet --noipc --nouserstartup --nousermodules -e "mcpserver"

codex mcp add nelson -- nelson-adv-cli --quiet --noipc --nouserstartup --nousermodules -e "mcpserver"

codex mcp add nelson -- nelson-adv-cli --quiet --noipc --nouserstartup --nousermodules -e "mcpserver('--nelson-display-mode=gui')"

Use Nelson MCP with an Ollama-backed agent.

# Terminal 1: start Ollama and make sure a model is available.
ollama serve
ollama pull llama3.2

# Terminal 2: configure your MCP-capable agent with:
#   model provider: Ollama
#   model endpoint: http://127.0.0.1:11434
#   model name: llama3.2
#   MCP server name: nelson
#   MCP server command:
nelson-adv-cli --quiet --noipc --nouserstartup --nousermodules -e "mcpserver('--workspace-root=D:/work/nelson-project --nelson-display-mode=adv-cli --max-output-characters=200000')"

Generic JSON-style MCP client configuration for an Ollama-backed agent.

{
  "model": {
    "provider": "ollama",
    "baseUrl": "http://127.0.0.1:11434",
    "name": "llama3.2"
  },
  "mcpServers": {
    "nelson": {
      "command": "nelson-adv-cli",
      "args": [
        "--quiet",
        "--noipc",
        "--nouserstartup",
        "--nousermodules",
        "-e",
        "mcpserver('--workspace-root=D:/work/nelson-project --nelson-display-mode=adv-cli --allow-execution=true --allow-format=true')"
      ]
    }
  }
}

Prompt an Ollama-backed agent to use Nelson tools.

Use the Nelson MCP server.
First call get_nelson_workspace.
Then call get_nelson_help for "plot".
Create and run a Nelson script that plots sin(0:0.1:10).
Return the PNG path from create_nelson_plot and summarize any Nelson output.