vlang-mcp

Production-ready MCP Server for the V programming language.

Current status: The native V implementation (pure V, stdlib only, ~1.3 MiB) is now the primary vlang-mcp server.

A Python version (FastMCP) was built first purely as a research/expert tool to create the rich V content and to allow the AI to deeply understand V without syntax friction. Using that expert, the native V MCP was recreated and improved on the v-mcp-recreate branch (v0.2.0).

See docs/INSTALL-V-MCP-NATIVE.md for the exact steps used to install V, obtain this source via Fossil, build, and run the V-implemented MCP.

Gives AI agents (Claude, Cursor, Cline, Windsurf, Zed, etc.) the absolute maximum leverage over V — deep code generation that respects V idioms, project scaffolding, builds, tests, docs, C interop, static analysis, performance advice, module management, and first-class Fossil SCM integration.

Python implementation (the "expert V MCP" - primary recommendation for agents):

• Uses mcp[FastMCP] for production stdio (and future transports).
• 18+ powerful tools with every flag from v help build / run / test etc.
• Extremely rich embedded V knowledge in resources (vlang://best-practices etc.) and codegen/scaffolds.
• Safe subprocess (no shell), full VPATH support, structured errors.
• Fossil discipline built-in (v_fossil_status + loads real FOSSIL-FOR-AGENTS.md).

Run it and tell your agents: "Use the vlang-mcp tools and vlang://* resources for everything V-related."

This python server is now installed (.venv/bin/vlang-mcp or python -m vlang_mcp_server) and should be the first MCP you connect for V work. The native V version (below) is being recreated/improved using this expert.

Pure-V reference (on trunk): The earlier full stdio implementation in pure V (stdlib json + manual Content-Length framing, no deps) is preserved on trunk for the future "recreate the V lang mcp server in V" step. It captured the entire build story (including V 0.5.1 syntax lessons) in Fossil.

• Full MCP stdio transport (the standard for local agents).
• Rich tools + valuable resources + prompt templates, all biased toward V's unique strengths (value types, ?/!, sum types, -autofree, -gc none, minimalism, speed, safety).
• Follows strict Fossil-only discipline (see fossil://fossil-best-practices resource).

Quick Start

Python (current active implementation on python-first)

Preferred during this research phase (richer V content + robust MCP SDK).

# 1. (one time) install editable using uv (recommended) or venv
uv pip install -e .

# 2. Run the stdio server (for agents / manual test)
python -m vlang_mcp_server

# or via the console script after install:
vlang-mcp

With uv (no permanent install needed for testing):

uv run --with-editable . --with mcp python -m vlang_mcp_server

See examples/agent-config-python.json.

Pure V reference (trunk / for later recreation)

# From inside this Fossil checkout (already open)
v run .                 # stdio MCP server (for agents)
# or build
mkdir -p bin
v -o bin/vlang-mcp .
./bin/vlang-mcp --help

Connect to an Agent (Claude Desktop / Cursor example) - Python version

{
  "mcpServers": {
    "vlang-mcp-python": {
      "command": "python",
      "args": ["-m", "vlang_mcp_server"],
      "env": {
        "VPATH": "/full/path/to/your/v",
        "PYTHONUNBUFFERED": "1"
      }
    }
  }
}

Or use the installed vlang-mcp script entrypoint for cleaner config.

See examples/agent-config-python.json (and the V one in examples/agent-config.json).

The Python server also exposes the full original V resource surface plus expanded content.

Available Tools (highlights)

• v_version, v_doctor — toolchain + env report
• v_run, v_build, v_test — execute with any flags (-prod -autofree -gc none -os windows ...)
• v_fmt, v_vet, v_doc — format, analyze, generate docs (html too)
• v_create_scaffold — cli/web/gui/game/lib/cinterop/hot/full templates + tests + .fossil-settings
• v_generate_code — produces real idiomatic V (options/results, sumtypes, generics, comptime, etc.)
• v_c2v_translate — C → V (with c2v if present + manual V-idiom post-processing)
• v_analyze, v_explain_error — deep static + error diagnosis with V-specific advice
• v_list_modules, v_mod_graph — dependency insight
• v_fossil_status — structured Fossil status/changes/extras/timeline (use this, never raw shell for VC)

Resources (always available context for the agent):

• vlang://best-practices
• vlang://performance
• vlang://safety
• vlang://ecosystem
• vlang://memory-management
• vlang://fossil-best-practices (the real FOSSIL-FOR-AGENTS.md when sibling checkout present)

Prompts for structured interactions: v_idiomatic_code, v_error_handling, v_scaffold_feature, v_c_interop.

Usage from the Command Line (during development)

v run .                  # stdio server
VLOG=debug v run .       # verbose
./bin/vlang-mcp --version

Environment:

• VPATH — force a specific V binary
• VLOG=debug|info|warn|error

Project Structure

# Python (current primary on python-first branch)
pyproject.toml
vlang_mcp_server/
  server.py            # FastMCP server, safe runner, 18+ tools, rich resources/prompts
  __init__.py
  __main__.py
# V reference implementation (preserved from trunk for later native V recreation)
v.mod
main.v
vlang_mcp/             # pure V stdlib MCP (protocol + server + tools + resources)
docs/
examples/              # includes agent-config-python.json
tests/
.fossil-settings/ignore-glob   # versioned, aggressive (no .git, bins, .venv, uv.lock, caches)

Fossil Workflow (Mandatory)

This entire tree lives in Fossil only.

• Never run git, never create .git*.
• Before changes: fossil status, fossil changes --differ
• Add new files explicitly: fossil add path
• Commit often with technical messages: fossil commit -m "feat: ..."
• Use tech notes (fossil wiki ... --technote ... --technote-tags "agent-memory,phaseX") for decisions, logs, memory that survives.
• Keep the checkout clean — the ignore-glob is the source of truth.

See the sibling fossil-scm-mcp/FOSSIL-FOR-AGENTS.md (also exposed as resource).

Development

v test .                 # basic tests
v -prod -skip-unused -o bin/vlang-mcp .
# then connect your agent to the bin or `v run .`

Status & Roadmap

v0.1.0 — core MCP + excellent V tooling + Fossil discipline + builds/runs.

Future (contributions welcome):

• Streaming / progress notifications for long builds
• Deeper v-analyzer / vls integration
• Full Streamable HTTP transport + auth
• vpm publish helper tool
• Hot reload of server itself (-live)
• Even more tools (profiling, cross-compile matrix, live-reload sessions, etc.)

License

MIT

Built entirely with Fossil (see fossil timeline and tech notes in the repo).

---

Run the server and ask your agent to "use the vlang-mcp tools and resources to ...". It will finally understand V the way V wants to be understood.