vfs (Virtual Function Signatures)

Core Positioning#

vfs is a local-first CLI tool and MCP Server that extracts exported function, class, interface, and type signatures from source code via AST-level parsing, stripping function bodies, imports, and comments to provide AI coding agents with minimal code structure summaries. Self-benchmarking shows a 98.6% token reduction (26,079 → 373), and 89.5% reduction compared to grep (3,537 → 373).

Signature Extraction & Denoising#

• AST-level parsing via go/ast (Go) and tree-sitter (other languages), outputting only exported symbol signatures
• Completely strips function bodies, import statements, comments, and other noise
• Uses line-based simple parsers for Dockerfile / Protobuf / SQL / YAML
• Does not include function implementation logic; does not support non-exported (private) symbol extraction (unless the language has no export semantics)

Multi-Language Coverage#

Supports 17 languages: Go, JavaScript, TypeScript, Python, Rust, Java, C#, Dart, Kotlin, Swift, Ruby, Solidity, HCL/Terraform, Dockerfile, Protobuf, SQL, and YAML. Single command can search across frontend and backend languages.

MCP Server Integration#

• Supports both stdio and HTTP transports
• Exposes three MCP tools: search, extract, list_languages
• Directly callable by MCP-compatible clients like Cursor, Claude Code, Claude Desktop, Windsurf, Cline, Continue, and Aider

stdio mode config:

{
  "mcpServers": {
    "vfs": {
      "command": "vfs",
      "args": ["mcp"]
    }
  }
}

HTTP mode config (for Docker / remote scenarios):

{
  "mcpServers": {
    "vfs": {
      "url": "http://localhost:8080/mcp"
    }
  }
}

Requires creating a rules file in the target repo (e.g., .cursor/rules/vfs-agent-search.mdc) instructing AI agents to prefer vfs over grep.

Security & Privacy#

• Local-first, fully offline operation
• Zero network access, zero telemetry, zero code storage
• Source code parsed in memory only and immediately discarded
• Persistence limited to ~/.vfs/history.jsonl for scan statistics

Observability#

• Built-in Web Dashboard (default port 3000) showing usage stats and token savings trends
• vfs stats command provides lifetime cumulative statistics (call count, tokens saved, average reduction rate)

CLI Commands#

Installation & Deployment#

Prebuilt binary (Linux):

curl -L https://github.com/TrNgTien/vfs/releases/latest/download/vfs-linux-amd64.tar.gz | tar xz
sudo mv vfs /usr/local/bin/

Build from source:

git clone https://github.com/TrNgTien/vfs.git && cd vfs
go install ./cmd/vfs

Docker:

docker build -t vfs-mcp .
docker run --rm -v $(pwd):/workspace -p 8080:8080 -p 3000:3000 vfs-mcp

Requirements: Go 1.24+, C compiler (for tree-sitter compilation), Docker (optional). macOS and Windows require building from source or using Docker.

Architecture Highlights#

• Entry layer: cmd/vfs/ — CLI entry point
• Core engine: internal/ — signature extraction engine with per-language parser implementations
• Parsing strategy tiers: Go uses go/ast; other mainstream languages use tree-sitter; Dockerfile/Protobuf/SQL/YAML use line parsers
• Benchmark module: pkg/bench/
• Containerization: Root Dockerfile + entrypoint.sh, customizable via VFS_PORT and VFS_DASHBOARD_PORT env vars

Use Cases#

• AI agent code discovery and targeting
• Large codebase structure navigation
• Cross-language signature search in polyglot monorepos
• File path and line number extraction in CI/scripts

Unconfirmed Information#

• First release date: repo has VERSION file and 41 commits, but README doesn't note the initial release date
• Author background: only GitHub username TrNgTien available, no personal page or org info found
• Specific tree-sitter versions not listed
• No independent website found in the repository