@veas/protocol

v0.1.11

Published

4 months ago

Universal protocol for knowledge management and project tracking systems - enabling seamless interoperability between platforms and AI assistants

Veas Protocol

Universal Protocol for Knowledge & Project Management Systems

A standardized, open-source protocol that enables seamless interoperability between knowledge bases, project management tools, and AI assistants. Build once, integrate everywhere.

🎯 Why This Protocol?

The modern workspace relies on various knowledge management and project tracking tools, each with its own API, data format, and integration requirements. This fragmentation creates:

Integration Complexity: Every tool needs custom integrations with every other tool
Data Silos: Information is locked within individual platforms
AI Limitations: AI assistants need separate implementations for each platform
Vendor Lock-in: Switching tools means losing integrations and automation

Veas Protocol solves this by providing a universal language that any tool can speak, enabling:

✅ Write Once, Integrate Everywhere: Implement the protocol once, work with any compatible tool
✅ AI-Native: Built with AI assistants in mind, following the Model Context Protocol (MCP) standard
✅ Data Portability: Move your data between platforms without losing functionality
✅ Future-Proof: As new tools emerge, they can adopt the protocol and instantly work with existing integrations

🏗️ Protocol Architecture

                        AI Assistants
                    (Claude, GPT, Copilot)
                             │
                             ▼
                    ┌─────────────────┐
                    │   MCP Adapter   │
                    └────────┬────────┘
                             │
┌────────────────────────────┼────────────────────────────┐
│                     Veas Protocol                        │
├───────────────────────────────────────────────────────────┤
│  📚 Knowledge Base  │  📋 Project Management  │  🔜 More  │
│  • Articles         │  • Projects             │  • CRM     │
│  • Folders          │  • Issues               │  • Calendar│
│  • Tags             │  • Sprints              │  • Chat    │
│  • Search           │  • Teams                │  • Files   │
└────────────┬───────────────┴───────────────┬────────────┘
             │                                │
             ▼                                ▼
┌─────────────────────────┐     ┌─────────────────────────┐
│   Protocol Providers    │     │   Protocol Consumers     │
│  (Implement Protocol)   │     │  (Use Protocol via SDK)  │
└─────────────────────────┘     └─────────────────────────┘
             │                                │
                       │
                       ▼
        Current Implementation: Veas Cloud
        
    Future Providers: Notion, GitHub, Jira, Confluence,
                     Obsidian, Linear, and more

📦 Protocol Domains

Knowledge Base Protocol

Standardized operations for content management systems:

Articles: Create, read, update, delete, publish
Folders: Hierarchical organization
Tags: Flexible categorization
Search: Full-text and metadata search
Versioning: Track changes over time

Project Management Protocol

Unified interface for project tracking systems:

Projects: Multi-tenant project spaces
Issues: Tasks, bugs, features with full lifecycle
Sprints: Time-boxed iterations
Teams: User and permission management
Workflows: Customizable state machines

Coming Soon

CRM Protocol: Customer relationship management
Calendar Protocol: Event and scheduling systems
Communication Protocol: Chat and messaging platforms
File Storage Protocol: Document and asset management

🚀 Quick Start

For Implementers (Building a Compatible Tool)

import { ProtocolProvider, KnowledgeBaseProtocol } from '@veas/protocol';

class MyKnowledgeBase implements KnowledgeBaseProtocol {
  async listArticles(params) {
    // Your implementation
    return { items: [...], total: 100 };
  }
  
  async createArticle(data) {
    // Your implementation
    return { id: '...', ...data };
  }
  
  // Implement other protocol methods...
}

// Register your implementation
const provider: ProtocolProvider = {
  name: 'my-knowledge-base',
  version: '1.0.0',
  knowledgeBase: new MyKnowledgeBase(),
  authenticate: async (credentials) => { /* ... */ },
  isConnected: () => true,
  disconnect: async () => { /* ... */ }
};

For Consumers (Using Protocol-Compatible Tools)

import { VeasProvider } from '@veas/protocol/providers/veas';

// Connect to Veas Cloud (currently supported)
const provider = new VeasProvider({
  apiUrl: 'https://api.veas.org',
  token: process.env.VEAS_PAT
});

// Use the protocol interface
const articles = await provider.knowledgeBase.listArticles({
  limit: 10,
  filters: { status: 'published' }
});

// Future: Connect to any protocol-compatible tool
// const provider = await connectToProvider('notion'); // Coming soon

For AI Assistants (MCP Server)

import { MCPAdapter } from '@veas/protocol/adapters/mcp';
import { YourProvider } from './your-provider';

// Create your protocol provider
const provider = new YourProvider();
await provider.authenticate({ /* credentials */ });

// Create MCP adapter
const adapter = new MCPAdapter(provider, {
  name: 'your-knowledge-base',
  description: 'Access your knowledge base via MCP'
});

// Start for Claude Desktop (stdio transport)
await adapter.serve({ transport: 'stdio' });

// Or start as HTTP server for web-based assistants
await adapter.serve({ 
  transport: 'http',
  port: 3000 
});

Configure in Claude Desktop (claude_desktop_config.json):

{
  "mcpServers": {
    "your-kb": {
      "command": "node",
      "args": ["/path/to/mcp-server.js"]
    }
  }
}

📋 Implementation Status

Currently Supported

| Platform | Knowledge Base | Project Management | Status | |----------|:--------------:|:------------------:|:------:| | Veas Cloud | ✅ | ✅ | Production Ready |

Roadmap - Future Provider Support

The protocol architecture is designed to support multiple providers. Future implementations planned:

| Platform | Knowledge Base | Project Management | Target | |----------|:--------------:|:------------------:|:------:| | Notion | 📋 | 📋 | Q4 2025 | | GitHub | 📋 | 📋 | Q4 2025 | | Obsidian | 📋 | - | Q1 2026 | | Confluence | 📋 | - | Q2 2026 | | Jira | - | 📋 | Q2 2026 | | Linear | - | 📋 | Q3 2026 |

Legend: ✅ Complete | 📋 Planned | - Not Applicable

🔧 For AI/MCP Integration

The protocol is designed to work seamlessly with AI assistants through the Model Context Protocol (MCP):

import { MCPAdapter } from '@veas/protocol/adapters/mcp';

// Expose any protocol provider as an MCP server
const adapter = new MCPAdapter(provider);

// Start MCP server for Claude Desktop
await adapter.serve({ transport: 'stdio' });

// AI assistants can now:
// - Browse and search knowledge bases
// - Create and manage projects
// - Update issues and track progress
// - Access any protocol-compatible tool

📘 See the complete MCP Integration Guide for:

Setting up MCP servers with different transports (stdio, WebSocket, SSE)
Configuring Claude Desktop and other AI assistants
Advanced patterns like multi-provider aggregation
Authentication and security best practices
Troubleshooting and performance optimization

📚 Documentation

Protocol Specification - Formal protocol definition
Implementation Guide - Step-by-step implementation instructions
MCP Integration Guide - Complete guide for AI assistant integration
API Reference - Complete API documentation
Examples - Real-world implementation examples
Migration Guide - Migrate from proprietary APIs

🤝 Community & Governance

Veas Protocol is an open standard developed by the community:

Protocol Evolution: Changes are proposed through VIPs (Veas Improvement Proposals)
Compatibility: Semantic versioning ensures backward compatibility
Certification: Tools can be certified as protocol-compliant
Working Groups: Domain-specific groups drive protocol development

Contributing

We welcome contributions from everyone! See CONTRIBUTING.md for:

How to propose protocol changes
Implementation guidelines
Testing requirements
Code of conduct

🛠️ Installation

# NPM
npm install @veas/protocol

# Yarn
yarn add @veas/protocol

# PNPM
pnpm add @veas/protocol

🧪 Testing

The protocol implementation includes comprehensive test coverage with a minimum threshold of 90% for all metrics.

# Run tests
pnpm test

# Run tests in watch mode
pnpm test:watch

# Run tests with coverage report
pnpm test -- --coverage

Coverage Requirements

| Metric | Threshold | |--------|-----------| | Statements | 90% | | Branches | 90% | | Functions | 90% | | Lines | 90% |

Tests are written using Vitest and include:

Unit tests for all protocol implementations
Integration tests for provider adapters
End-to-end tests for MCP server functionality
Mock implementations for testing consumer code

📦 What's Included

@veas/protocol
├── /protocols      # Protocol definitions and interfaces
│   ├── /knowledge-base    # Knowledge management protocol
│   ├── /project-management # Project tracking protocol
│   └── /common            # Shared types and utilities
├── /adapters       # Protocol adapters
│   └── /mcp              # Model Context Protocol adapter
├── /providers      # Reference implementations
│   └── /veas             # Veas cloud provider
└── /sdk           # Helper libraries for implementers

🌟 Use Cases

For Organizations

Tool Migration: Switch between platforms without losing integrations
Multi-Tool Workflows: Seamlessly work across different tools
Custom Integrations: Build once, work with all protocol-compatible tools

For Tool Developers

Instant Ecosystem: Immediately compatible with all protocol tools
Reduced Development: No need to build individual integrations
AI-Ready: Automatic compatibility with AI assistants

For AI/Automation

Universal Access: One protocol to access all tools
Consistent Interface: Same operations across different platforms
Rich Capabilities: Full CRUD operations, search, and more

🎯 Roadmap

Phase 1: Foundation (Current)

✅ Knowledge Base Protocol v1.0
✅ Project Management Protocol v1.0
✅ MCP Adapter
✅ Reference Implementation (Veas)

Phase 2: Ecosystem (Q4 2025 - Q1 2026)

📋 Notion Provider
📋 GitHub Provider
📋 Obsidian Provider
📋 Protocol Certification Program

Phase 3: Expansion (2026)

📋 Confluence Provider
📋 Jira Provider
📋 Linear Provider
📋 CRM Protocol
📋 Calendar Protocol
📋 File Storage Protocol
📋 Communication Protocol

🛠️ Development

# Install dependencies
npm install

# Run tests
npm test

# Run tests with coverage
npm run test:coverage

# Build the package
npm run build

# Type checking
npm run typecheck

# Linting
npm run lint

Test Coverage

This project maintains high test coverage standards with automated reporting via Codecov:

Current Coverage: See badge above (automatically updated via CI)
Minimum threshold: 70% for statements and lines
Automated reporting: Coverage reports are uploaded to Codecov on every push
Local coverage: Run npm run test:coverage to view coverage locally
Pull Request checks: Codecov comments on PRs with coverage changes

Running Tests Locally:

npm test              # Run all tests
npm run test:watch    # Run tests in watch mode  
npm run test:coverage # Generate coverage report with detailed breakdown

CI Integration:

Tests run with coverage on every push and PR
Coverage reports are automatically uploaded to Codecov
Build fails if coverage drops below 70%
Detailed reports available at codecov.io/gh/veas-org/veas-protocol

📄 License

Documentation • API Reference • Discord Community • GitHub

Built with ❤️ by the open-source community