Vingularity Protocol

Auto-scan any codebase and generate a unified mind map showing every project, API, database, agent, port, and inter-system connection.

MCP Server + CLI — works with Claude Code, Claude Desktop, or standalone.

 ██╗   ██╗██╗███╗   ██╗ ██████╗ ██╗   ██╗██╗      █████╗ ██████╗ ██╗████████╗██╗   ██╗
 ██║   ██║██║████╗  ██║██╔════╝ ██║   ██║██║     ██╔══██╗██╔══██╗██║╚══██╔══╝╚██╗ ██╔╝
 ██║   ██║██║██╔██╗ ██║██║  ███╗██║   ██║██║     ███████║██████╔╝██║   ██║    ╚████╔╝
 ╚██╗ ██╔╝██║██║╚██╗██║██║   ██║██║   ██║██║     ██╔══██║██╔══██╗██║   ██║     ╚██╔╝
  ╚████╔╝ ██║██║ ╚████║╚██████╔╝╚██████╔╝███████╗██║  ██║██║  ██║██║   ██║      ██║
   ╚═══╝  ╚═╝╚═╝  ╚═══╝ ╚═════╝  ╚═════╝ ╚══════╝╚═╝  ╚═╝╚═╝  ╚═╝╚═╝   ╚═╝      ╚═╝

Quick Start

# Zero-install scan
npx vingularity-protocol scan .

# Install globally
npm install -g vingularity-protocol
vingularity scan /path/to/your/projects

What It Detects

Category	Trigger Files	Extracted
Projects	package.json, requirements.txt, pyproject.toml, Cargo.toml, go.mod, Gemfile, composer.json	Name, tech stack, framework, dependencies, scripts
APIs	route.ts, app.py, server.ts + regex patterns	HTTP method, path, framework, source file
Databases	prisma/schema.prisma, docker-compose DB images, .env refs	Type, port, models, connection refs
AI/Agents	.mcp.json, CLAUDE.md, AGENTS.md, LLM env vars	Type, name, config details
Infrastructure	Dockerfile, docker-compose.yml, nginx.conf, .service, render.yaml	Services, ports, images, volumes
Documentation	README.md, CLAUDE.md, ARCHITECTURE*.md	File paths, types
Connections	Cross-analysis of ports, env vars, shared deps	From/to, type, details

CLI Commands

vingularity scan [path]                    # Scan a directory tree
vingularity scan . -d 5 -f json -o out.json  # Custom depth, format, output file
vingularity map [-f markdown|json|html]    # Generate mind map from last scan
vingularity ports                          # Show all detected ports
vingularity connections [--project id]     # Show inter-system connections
vingularity export [format] [-o file]      # Export scan results
vingularity serve                          # Start MCP server (stdio)

MCP Server

Claude Code

Add to your .mcp.json:

{
  "mcpServers": {
    "vingularity": {
      "command": "npx",
      "args": ["-y", "vingularity-protocol", "serve"]
    }
  }
}

Claude Desktop

Add to your Claude Desktop config:

{
  "mcpServers": {
    "vingularity": {
      "command": "npx",
      "args": ["-y", "vingularity-protocol", "serve"]
    }
  }
}

MCP Tools

Tool	Description
`scan_ecosystem`	Full directory scan (path, depth, includeHidden)
`scan_project`	Single project deep scan
`get_mind_map`	Return mind map (markdown or json)
`get_connections`	Return connection graph (optional project filter)
`get_port_map`	All detected ports/services
`get_tech_stack`	Technology inventory

MCP Resources

URI	Description
`vingularity://mind-map`	Full mind map
`vingularity://connections`	Connection graph
`vingularity://inventory`	System inventory

Configuration

Create vingularity.config.yaml in your project root or ~/.vingularity/config.yaml:

scan:
  maxDepth: 8
  maxFileSize: 1048576
  followSymlinks: false

ignore:
  - "*.log"
  - "*.tmp"

output:
  format: markdown
  includeTimestamp: true
  includeStats: true

analyzers:
  project: true
  api: true
  database: true
  agent: true
  infra: true
  docs: true

Output Formats

Markdown — ORACLE.md-style mind map with ASCII art, tables, and connection diagrams
JSON — Full structured scan result for programmatic use
HTML — Dark-themed page with Mermaid.js connection diagram

Architecture

vingularity-protocol/
├── src/
│   ├── types.ts          # All types + Zod schemas
│   ├── config.ts         # Config loader (YAML regex + defaults)
│   ├── scanner/          # Directory walker + ignore patterns
│   ├── analyzers/        # 6 analyzers: project, api, database, agent, infra, docs
│   ├── graph/            # Connection builder + port resolver
│   ├── renderers/        # JSON, Markdown, HTML output
│   ├── mcp/              # MCP server (6 tools, 3 resources)
│   └── cli/              # Commander.js CLI

3 runtime dependencies: @modelcontextprotocol/sdk, commander, zod

Requirements

Node.js 18.17+

License

MIT

@vltrn/vingularity-protocol

Quick Install