Vingularity Protocol

Powered by VLTRN | Map everything. Connect everything. Understand everything.

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

Best used with Carbon[6] OiS — Vingularity Protocol is the intelligence layer that maps your entire ecosystem. Pair it with Carbon[6] OiS for full orchestration.

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.

Standalone power. Ecosystem amplified.

Quick Start

# Zero-install scan
npx @vltrn/vingularity-protocol scan .

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

# Export as HTML with connection diagrams
vingularity scan . -f html -o mind-map.html

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", "@vltrn/vingularity-protocol", "serve"]
    }
  }
}

Claude Desktop

Add to your Claude Desktop config:

{
  "mcpServers": {
    "vingularity": {
      "command": "npx",
      "args": ["-y", "@vltrn/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 (Carbon6 color system)

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

Carbon6 Cloud API

Vingularity Protocol connects to the Carbon6 API at https://api.carbon6.agency for cloud sync, remote monitoring, and multi-instance ecosystem intelligence.

Register & Sync

# Register this machine with Carbon6
vingularity register --label "my-workstation"

# Scan and auto-sync to cloud
vingularity scan . --sync

# Sync last scan manually
vingularity sync

# Scan + sync in one shot
vingularity sync --scan-first /path/to/projects

# Check connectivity and instance status
vingularity status

# View sync history
vingularity history -n 20

# Remove registration
vingularity deregister

Environment Override

# Use a custom API endpoint (default: https://api.carbon6.agency)
export VINGULARITY_API_URL=https://your-custom-endpoint.com

MCP Cloud Tools

| Tool | Description | |------|-------------| | sync_to_cloud | Sync scan results to Carbon6 API (optional: scan first) | | cloud_status | Check API registration and connectivity | | cloud_register | Register instance with Carbon6 API |

API Endpoints

| Method | Path | Description | |--------|------|-------------| | POST | /v1/vingularity/register | Register new instance | | POST | /v1/vingularity/sync | Sync scan results | | GET | /v1/vingularity/instances/:id | Get instance status | | POST | /v1/vingularity/instances/:id/heartbeat | Instance heartbeat | | GET | /v1/vingularity/instances/:id/scans | List sync history | | DELETE | /v1/vingularity/instances/:id | Deregister instance |

Credentials

Stored at ~/.vingularity/credentials.json (chmod 600). Contains instance ID and API key — never committed to git.

Carbon[6] OiS Integration

Vingularity Protocol is the intelligence layer that maps your entire ecosystem. When connected to Carbon[6] OiS, scan results feed directly into the Orchestration and Intelligence System for real-time infrastructure awareness.

• Ecosystem Discovery — Vingularity scans and maps every project, service, and connection
• OiS Orchestration — Carbon[6] OiS uses that map to orchestrate, monitor, and coordinate
• Continuous Awareness — Schedule scans to keep OiS updated as your infrastructure evolves

Vingularity sees. OiS acts.

Contributing

See CONTRIBUTING.md for guidelines.

Requirements

• Node.js 18.17+

License

MIT — see LICENSE

(c) 2026 VLTRN Family Office. All rights reserved.

Vingularity Protocol is a trademark of VLTRN Family Office. Carbon6 and Carbon[6] OiS are trademarks of Carbon6 LLC.

VLTRN Family Office | 651 N Broad St, Suite 201, Middletown, DE 19709 | [email protected]