# 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

```bash
# 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](/development/architecture.md)

**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](/development/building.md)

**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](/development/testing.md)

**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](/development/plugins.md)

**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](https://github.com/vcon-dev/vcon-mcp/blob/main/docs/development/custom-tools.md)

**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](https://github.com/vcon-dev/vcon-mcp/blob/main/docs/development/extending.md)

**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](/development/embeddings.md)

**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](/development/contributing.md)

**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](/development/code-style.md)

**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](/development/documentation.md)

**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

```bash
# 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

```bash
# 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

```bash
# 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

```bash
# 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**:
   * Read [Architecture](/development/architecture.md) to understand the system
   * Follow [Building Guide](/development/building.md) to set up locally
   * Review [Code Style Guide](/development/code-style.md) for standards
2. **Make Your First Contribution**:
   * Check issues tagged with `good-first-issue`
   * Read [Contributing Guide](/development/contributing.md)
   * Start with documentation or tests
3. **Advance Your Skills**:
   * Review [Extending Guide](https://github.com/vcon-dev/vcon-mcp/blob/main/docs/development/extending.md) to understand all options
   * Create a [Plugin](/development/plugins.md) to add functionality
   * Develop a [Custom Tool](https://github.com/vcon-dev/vcon-mcp/blob/main/docs/development/custom-tools.md)
   * Implement [Advanced Search](/development/embeddings.md)

### For Advanced Developers

1. **Deep Dive**:
   * Study the [Architecture](/development/architecture.md) in detail
   * Review database schema and RPC functions
   * Understand plugin system internals
2. **Extend the System**:
   * Master the [Extension Guide](https://github.com/vcon-dev/vcon-mcp/blob/main/docs/development/extending.md)
   * 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

```bash
# 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

```bash
# Test with MCP Inspector
npm run test:console

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

### Compliance Tests

```bash
# 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](/development/contributing.md) 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](https://github.com/vcon-dev/vcon-mcp/blob/main/LICENSE/README.md) for details.

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

***

**Ready to contribute?** Start with the [Contributing Guide](/development/contributing.md) and choose a task that interests you!

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


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://mcp.conserver.io/development/index.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.