Overview

Everything you need to build, extend, and contribute to the vCon MCP Server.

Overview

This comprehensive development guide covers all aspects of working with the vCon MCP Server codebase:

  • System Architecture - Understanding the design and components

  • Building & Testing - Getting the server running locally

  • Extending Functionality - Creating plugins and custom tools

  • Contributing - Guidelines for code, testing, and documentation

  • Best Practices - Code style, patterns, and standards

Quick Start

# Clone the repository
git clone https://github.com/vcon-dev/vcon-mcp.git
cd vcon-mcp

# Install dependencies
npm install

# Set up environment
cp .env.example .env
# Edit .env with your Supabase credentials

# Build the project
npm run build

# Run tests
npm test

# Start development server
npm run dev

Documentation Sections

📐 Architecture

Deep dive into system design:

  • Component architecture and layers

  • Data flow and request handling

  • Plugin system architecture

  • Database design and search strategies

  • Performance considerations

  • Security architecture

Perfect for: Understanding how everything fits together

🔨 Building from Source

Complete build guide from scratch:

  • Prerequisites and environment setup

  • Database schema setup

  • Project structure creation

  • Core implementation

  • MCP server configuration

  • Testing and validation

  • Deployment preparation

Perfect for: First-time setup and deployment

🧪 Testing

Comprehensive testing guide:

  • Unit testing with Vitest

  • Integration testing patterns

  • IETF spec compliance tests

  • MCP tool testing

  • Test fixtures and utilities

  • Coverage requirements

  • CI/CD integration

Perfect for: Ensuring code quality and correctness

🔌 Plugin Development

Create plugins to extend the server:

  • Plugin interface and lifecycle hooks

  • Operation hooks (create, read, update, delete, search)

  • Registering custom tools and resources

  • Plugin configuration

  • Example plugins (logging, access control)

  • Testing plugins

  • Publishing plugins

Perfect for: Adding custom functionality without modifying core

🛠️ Custom Tools

Develop custom MCP tools:

  • Tool structure and schemas

  • Input validation with Zod

  • Implementing tool handlers

  • Database access patterns

  • External API integration

  • Testing custom tools

  • Best practices and examples

Perfect for: Adding new capabilities to the MCP interface

🔧 Extending the Server

Complete extension guide for resources, prompts, tools, and plugins:

  • When to use each extension type

  • Adding custom resources (discoverable data access)

  • Creating custom prompts (guided query templates)

  • Building custom tools (executable operations)

  • Packaging as plugins (reusable modules)

  • Complete real-world examples

  • Best practices and patterns

Perfect for: Understanding all extension options and choosing the right approach

🤖 Embeddings & Search

AI-powered semantic search:

  • pgvector extension setup

  • Embedding generation (OpenAI, local models)

  • Vector indexing (HNSW, IVFFlat)

  • Search strategies (keyword, semantic, hybrid)

  • Performance optimization

  • Cost considerations

  • Batch processing

Perfect for: Implementing AI-powered search features

🤝 Contributing Guide

How to contribute to the project:

  • Code of conduct

  • Getting started with contributions

  • Development workflow

  • Pull request process

  • Commit message conventions

  • Code review expectations

  • Recognition and community

Perfect for: New contributors and community guidelines

📝 Code Style Guide

Coding standards and best practices:

  • TypeScript style guidelines

  • Naming conventions

  • File organization patterns

  • Comments and documentation

  • Error handling patterns

  • Testing style

  • Git practices

Perfect for: Writing consistent, maintainable code

📚 Documentation Standards

Writing and maintaining docs:

  • Documentation types (API, guides, examples)

  • Writing style and tone

  • Markdown standards

  • Code example guidelines

  • API documentation templates

  • User guide structure

  • Build and deployment

Perfect for: Contributing to documentation

Project Structure

vcon-mcp/
├── src/
│   ├── index.ts              # MCP server entry point
│   ├── types/                # TypeScript type definitions
│   │   ├── vcon.ts          # IETF vCon types
│   │   └── mcp.ts           # MCP protocol types
│   ├── db/                   # Database layer
│   │   ├── client.ts        # Supabase client
│   │   └── queries.ts       # Database queries
│   ├── tools/                # MCP tools
│   │   ├── vcon-crud.ts     # CRUD operations
│   │   ├── search-tools.ts  # Search operations
│   │   └── tag-tools.ts     # Tag management
│   ├── resources/            # MCP resources
│   │   └── index.ts         # Resource handlers
│   ├── prompts/              # MCP prompts
│   │   └── index.ts         # Prompt templates
│   ├── hooks/                # Plugin system
│   │   └── index.ts         # Plugin interface
│   └── utils/                # Utilities
│       ├── validation.ts    # vCon validation
│       └── logger.ts        # Logging utilities
├── tests/                    # Test suites
│   ├── crud.test.ts         # CRUD tests
│   ├── search.test.ts       # Search tests
│   └── fixtures/            # Test data
├── docs/                     # Documentation
│   ├── guide/               # User guides
│   ├── api/                 # API reference
│   ├── development/         # Developer guides
│   ├── examples/            # Code examples
│   └── reference/           # Technical specs
├── supabase/                 # Database
│   └── migrations/          # SQL migrations
├── scripts/                  # Helper scripts
│   └── test-mcp-tools.ts   # Tool testing script
└── .github/                  # GitHub config
    └── workflows/           # CI/CD pipelines

Tech Stack

Core Technologies

  • Language: TypeScript 5.x

  • Runtime: Node.js 18+

  • Database: PostgreSQL 15+ (via Supabase)

  • Protocol: MCP (Model Context Protocol)

  • Validation: Zod

  • Testing: Vitest

  • Build: TypeScript Compiler

  • Documentation: VitePress

Key Libraries

  • @modelcontextprotocol/sdk - MCP protocol implementation

  • @supabase/supabase-js - Database client

  • zod - Runtime type validation

  • vitest - Testing framework

  • pgvector - Vector similarity search

Development Workflow

1. Set Up Environment

# Install dependencies
npm install

# Configure environment
cp .env.example .env
# Edit .env with your credentials

# Initialize database
# Run migrations in Supabase dashboard

2. Make Changes

# Create feature branch
git checkout -b feature/your-feature

# Make your changes
# Edit src/ files

# Build and test
npm run build
npm test

3. Test Locally

# Run dev server
npm run dev

# Test with MCP Inspector
npm run test:console

# Or test with Claude Desktop
# Update claude_desktop_config.json

4. Submit Changes

# Run linter
npm run lint

# Run tests
npm test

# Commit changes
git add .
git commit -m "feat(scope): description"

# Push and create PR
git push origin feature/your-feature

Learning Path

For New Contributors

  1. Start Here:

  2. Make Your First Contribution:

    • Check issues tagged with good-first-issue

    • Read Contributing Guide

    • Start with documentation or tests

  3. Advance Your Skills:

For Advanced Developers

  1. Deep Dive:

    • Study the Architecture in detail

    • Review database schema and RPC functions

    • Understand plugin system internals

  2. Extend the System:

    • Master the Extension Guide

    • Build complex plugins with resources and tools

    • Add new search algorithms

    • Optimize performance

  3. Contribute Back:

    • Improve core functionality

    • Enhance documentation

    • Mentor new contributors

Testing Your Changes

Unit Tests

# Run all tests
npm test

# Run specific test file
npm test -- search.test.ts

# Run with coverage
npm run test:coverage

# Watch mode
npm test -- --watch

Integration Tests

# Test with MCP Inspector
npm run test:console

# Test with real client
# Configure Claude Desktop and test manually

Compliance Tests

# Run IETF spec compliance tests
npm run test:compliance

Getting Help

Resources

  • Documentation: Browse /docs for comprehensive guides

  • GitHub Issues: Search for similar issues or questions

  • GitHub Discussions: Ask questions and share ideas

  • Code Examples: Check /tests and /docs/examples

  • IETF Spec: Read the vCon specification for details

Where to Ask

  • Questions: GitHub Discussions

  • Bugs: GitHub Issues with bug report template

  • Features: GitHub Issues with feature request template

  • Security: Email maintainers privately

Contributing

We welcome contributions of all types:

  • Code: New features, bug fixes, optimizations

  • Documentation: Guides, examples, API docs

  • Testing: Test cases, fixtures, tools

  • Design: Architecture proposals, refactoring

  • Community: Answering questions, reviewing PRs

See Contributing Guide for detailed instructions.

Community

  • GitHub: https://github.com/vcon-dev/vcon-mcp

  • Issues: Report bugs and request features

  • Discussions: Ask questions and share ideas

  • IETF vCon WG: https://datatracker.ietf.org/wg/vcon/

License

The vCon MCP Server is released under the MIT License. See LICENSE for details.

By contributing, you agree that your contributions will be licensed under the MIT License.

Ready to contribute? Start with the Contributing Guide and choose a task that interests you!

Need help? Don't hesitate to ask questions in GitHub Discussions. We're here to help! 🚀

PreviousJSON SchemaNextArchitecture

Last updated