Utilizes Cloudflare D1 database for persistent context storage and Cloudflare Workers AI for context summarization and auto-tagging capabilities
Semantic Context MCP
Reference implementation of Semantic Intent as Single Source of Truth patterns
A Model Context Protocol (MCP) server demonstrating semantic anchoring, intent preservation, and observable property patterns for AI-assisted development.
π Table of Contents
π― What Makes This Different
This isn't just another MCP serverβit's a reference implementation of proven semantic intent patterns:
β Semantic Anchoring: Decisions based on meaning, not technical characteristics
β Intent Preservation: Semantic contracts maintained through all transformations
β Observable Properties: Behavior anchored to directly observable semantic markers
β Domain Boundaries: Clear semantic ownership across layers
Built on research from Semantic Intent as Single Source of Truth, this implementation demonstrates how to build maintainable, AI-friendly codebases that preserve intent.
π Quick Start
Prerequisites
Node.js 20.x or higher
Cloudflare account (free tier works)
Wrangler CLI:
npm install -g wrangler
Installation
Clone the repository
git clone https://github.com/semanticintent/semantic-context-mcp.git cd semantic-context-mcpInstall dependencies
npm installConfigure Wrangler
Copy the example configuration:
cp wrangler.jsonc.example wrangler.jsoncCreate a D1 database:
wrangler d1 create mcp-contextUpdate
wrangler.jsonc
with your database ID:{ "d1_databases": [{ "database_id": "your-database-id-from-above-command" }] }Run database migrations
# Local development wrangler d1 execute mcp-context --local --file=./migrations/0001_initial_schema.sql # Production wrangler d1 execute mcp-context --file=./migrations/0001_initial_schema.sqlStart development server
npm run dev
Deploy to Production
Your MCP server will be available at: semantic-context-mcp.<your-account>.workers.dev
π Learning from This Implementation
This codebase demonstrates semantic intent patterns throughout:
Architecture Files:
src/index.ts - Dependency injection composition root (74 lines)
src/domain/ - Business logic layer (ContextSnapshot, ContextService)
src/application/ - Orchestration layer (handlers and protocol)
src/infrastructure/ - Technical adapters (D1, AI, CORS)
src/presentation/ - HTTP routing layer (MCPRouter)
Documentation & Patterns:
migrations/0001_initial_schema.sql - Schema with semantic intent documentation
src/types.ts - Type-safe semantic contracts
SEMANTIC_ANCHORING_GOVERNANCE.md - Governance rules and patterns
REFACTORING_PLAN.md - Complete refactoring documentation
Each file includes comprehensive comments explaining WHY decisions preserve semantic intent, not just WHAT the code does.
Connect to Cloudflare AI Playground
You can connect to your MCP server from the Cloudflare AI Playground, which is a remote MCP client:
Enter your deployed MCP server URL (
remote-mcp-server-authless.<your-account>.workers.dev/sse
)You can now use your MCP tools directly from the playground!
Connect Claude Desktop to your MCP server
You can also connect to your remote MCP server from local MCP clients, by using the mcp-remote proxy.
To connect to your MCP server from Claude Desktop, follow Anthropic's Quickstart and within Claude Desktop go to Settings > Developer > Edit Config.
Update with this configuration:
Restart Claude and you should see the tools become available.
ποΈ Architecture
This project demonstrates Domain-Driven Hexagonal Architecture with clean separation of concerns:
Layer Responsibilities:
Domain Layer (src/domain/):
Pure business logic independent of infrastructure
ContextSnapshot
: Entity with validation rulesContextService
: Core business operations
Application Layer (src/application/):
Orchestrates domain operations
ToolExecutionHandler
: Translates MCP tools to domain operationsMCPProtocolHandler
: Manages JSON-RPC protocol
Infrastructure Layer (src/infrastructure/):
Technical adapters implementing ports (interfaces)
D1ContextRepository
: Cloudflare D1 persistenceCloudflareAIProvider
: Workers AI integrationCORSMiddleware
: Cross-cutting concerns
Presentation Layer (src/presentation/):
HTTP routing and request handling
MCPRouter
: Routes requests to appropriate handlers
Composition Root (src/index.ts):
Dependency injection
Wires all layers together
74 lines (down from 483 - 90% reduction)
Benefits:
β Testability: Each layer independently testable
β Maintainability: Clear responsibilities per layer
β Flexibility: Swap infrastructure (D1 β Postgres) without touching domain
β Semantic Intent: Comprehensive documentation of WHY
β Type Safety: Strong TypeScript contracts throughout
Features
save_context: Save conversation context with AI-powered summarization and auto-tagging
load_context: Retrieve relevant context for a project
search_context: Search contexts using keyword matching
π§ͺ Testing
This project includes comprehensive unit tests with 70 tests covering all architectural layers.
Run Tests
Test Coverage
β Domain Layer: 15 tests (ContextSnapshot validation, ContextService orchestration)
β Application Layer: 10 tests (ToolExecutionHandler, MCP tool dispatch)
β Infrastructure Layer: 20 tests (D1Repository, CloudflareAIProvider with fallbacks)
β Presentation Layer: 12 tests (MCPRouter, CORS, error handling)
β Integration: 13 tests (End-to-end service flows)
Test Structure
Tests are co-located with source files using the .test.ts
suffix:
All tests use Vitest with mocking for external dependencies (D1, AI services).
Continuous Integration
This project uses GitHub Actions for automated testing and quality checks.
Automated Checks on Every Push/PR:
β TypeScript compilation (
npm run type-check
)β Unit tests (
npm test
)β Test coverage reports
β Code formatting (Biome)
β Linting (Biome)
Status Badges:
CI status displayed at top of README
Automatically updates on each commit
Shows passing/failing state
Workflow Configuration: .github/workflows/ci.yml
The CI pipeline runs on Node.js 20.x and ensures code quality before merging.
Database Setup
This project uses Cloudflare D1 for persistent context storage.
Initial Setup
Create D1 Database:
wrangler d1 create mcp-contextUpdate with your database ID:
{ "d1_databases": [ { "binding": "DB", "database_name": "mcp-context", "database_id": "your-database-id-here" } ] }Run Initial Migration:
wrangler d1 execute mcp-context --file=./migrations/0001_initial_schema.sql
Local Development
For local testing, initialize the local D1 database:
Verify Schema
Check that tables were created successfully:
Database Migrations
All database schema changes are managed through versioned migration files in migrations/
:
0001_initial_schema.sql
- Initial context snapshots table with semantic indexes
See migrations/README.md for detailed migration management guide.
License
This project is licensed under the MIT License - see the LICENSE file for details.
π¬ Research Foundation
This implementation is based on the research paper "Semantic Intent as Single Source of Truth: Immutable Governance for AI-Assisted Development".
Core Principles Applied:
Semantic Over Structural - Use meaning, not technical characteristics
Intent Preservation - Maintain semantic contracts through transformations
Observable Anchoring - Base behavior on directly observable properties
Immutable Governance - Protect semantic integrity at runtime
Related Resources:
Research Paper (coming soon)
semanticintent.dev (coming soon)
π€ Contributing
We welcome contributions! This is a reference implementation, so contributions should maintain semantic intent principles.
How to Contribute
Read the guidelines: CONTRIBUTING.md
Check existing issues: Avoid duplicates
Follow the architecture: Maintain layer boundaries
Add tests: All changes need test coverage
Document intent: Explain WHY, not just WHAT
Contribution Standards
β Follow semantic intent patterns
β Maintain hexagonal architecture
β Add comprehensive tests
β Include semantic documentation
β Pass all CI checks
Quick Links:
Contributing Guide - Detailed guidelines
Code of Conduct - Community standards
Architecture Guide - Design principles
Security Policy - Report vulnerabilities
Community
π¬ Discussions - Ask questions
π Issues - Report bugs
π Security - Report vulnerabilities privately
π Security
Security is a top priority. Please review our Security Policy for:
Secrets management best practices
What to commit / what to exclude
Reporting security vulnerabilities
Security checklist for deployment
Found a vulnerability? Email: security@semanticintent.dev
This server cannot be installed
remote-capable server
The server can be hosted and run remotely because it primarily relies on remote services or has no dependency on the local environment.
Enables AI assistants to save, load, and search conversation context with AI-powered summarization and auto-tagging. Demonstrates semantic intent patterns and hexagonal architecture for maintainable AI-assisted development.