Engineering Standards MCP Server

A Model Context Protocol (MCP) server for managing engineering standards, practices, and processes. This server provides AI assistants with structured access to your organization's engineering knowledge base through a standardized interface.

Table of Contents

• Features
• Installation
• Usage
• Architecture
• Tools
• File Naming Conventions
• Configuration
• Contributing
• License

Features

• Multi-dimensional Organization: Standards organized by type, tier, process, and tags
• Full-Text Search: Powerful search with relevance scoring across all standards
• Flexible Output: Support for both JSON and Markdown response formats
• In-Memory Caching: High-performance indexing for fast retrieval
• Type-Safe: Complete TypeScript implementation with strict validation
• MCP-Compliant: Built on the Model Context Protocol SDK v1.24+
• REST API: HTTP transport for easy integration with AI assistants
• CRUD Operations: Create, read, update, and manage standards programmatically

Installation

Prerequisites

• Node.js >= 18.0.0
• npm (comes with Node.js)

Step-by-Step Setup

1. Clone or extract the project:

cd engineering-standards-mcp-server

2. Install dependencies:

npm install

This will install approximately 192 packages including:

• @modelcontextprotocol/sdk - MCP SDK
• express - HTTP server
• zod - Schema validation
• gray-matter - Markdown frontmatter parsing
• glob - File pattern matching

3. Verify installation:

npm start

Expected output:

============================================================
engineering-standards-mcp-server v1.0.0
============================================================

✓ Server running on http://localhost:3000/mcp
✓ Health check: http://localhost:3000/health

Ready to accept MCP connections.

Usage

Starting the Server

Development mode (with auto-reload):

npm run dev

Production mode:

npm start

Docker Deployment

Using Docker Compose (Recommended):

docker-compose up -d

Using Docker CLI:

# Build the image
npm run docker:build

# Run the container
npm run docker:run

For detailed Docker deployment instructions, see DOCKER.md.

Connecting AI Clients

Claude Desktop:

claude mcp add --transport http engineering-standards http://localhost:3000/mcp

MCP Inspector (for testing):

npx @modelcontextprotocol/inspector
# Connect to: http://localhost:3000/mcp

VS Code (if supported):

code --add-mcp '{"name":"engineering-standards","type":"http","url":"http://localhost:3000/mcp"}'

Example Queries

Once connected, you can interact with the server through your AI assistant:

• "List all active backend standards"
• "Search for Spring Boot security practices"
• "Show me the frontend development principles"
• "Create a new standard for API testing"
• "Update the database performance standard"

Health Check

Verify the server is running:

Invoke-WebRequest -Uri http://localhost:3000/health

Architecture

Project Structure

engineering-standards-mcp-server/
├── src/
│   ├── index.ts              # Main server entry point
│   ├── constants.ts          # Configuration constants
│   ├── types.ts              # TypeScript type definitions
│   ├── schemas/
│   │   └── metadata.ts       # Zod validation schemas
│   ├── services/
│   │   ├── validator.ts      # Metadata validation
│   │   ├── parser.ts         # Markdown parsing
│   │   ├── storage.ts        # File system operations
│   │   └── indexer.ts        # In-memory indexing
│   └── tools/
│       ├── list.ts           # List index tool
│       ├── get.ts            # Get standard tool
│       ├── search.ts         # Search tool
│       ├── metadata.ts       # Metadata tool
│       ├── create.ts         # Create tool
│       └── update.ts         # Update tool
├── data/                     # Knowledge base directory
├── scripts/
│   └── migrate-standards.ts  # Migration utility
├── package.json
├── tsconfig.json
└── README.md

Service Layers

1. Validator Service: Validates standard metadata using Zod schemas
2. Parser Service: Parses Markdown files with frontmatter
3. Storage Service: Manages file system operations
4. Indexer Service: Maintains in-memory search index

Tools

The server exposes 6 MCP tools following VS Code best practices:

1. list_standards

Browse all standards organized hierarchically by type, tier, and process.

Parameters: filterType, filterTier, filterProcess, filterStatus Output: JSON or Markdown

2. get_standard

Retrieve a specific standard by its file path or metadata.

Input: File path or metadata combination (type, tier, process) Output: Full standard content with metadata

3. search_standards

Full-text search across all standards with relevance scoring.

Input: Query string, optional filters (filterType, filterTier, etc.), limit Output: Ranked search results

4. get_standards_metadata

Query metadata only without fetching full content.

Parameters: filterType, filterTier, filterProcess, filterStatus, filterTags

5. create_standard

Create a new standard with automatic validation and file naming.

Input: Metadata and content Output: Created standard path

6. update_standard

Update existing standards with version bumping.

Input: Path, updated content, versionBump type Output: Updated standard details

File Naming Conventions

Standards must follow the naming pattern:

{type}-{tier}-{process}-{slug}-{status}.md

Components

• type: principle | standard | practice | tech-stack | process
• tier: frontend | backend | database | infrastructure | security
• process: development | testing | delivery | operations
• slug: Descriptive kebab-case identifier
• status: active | draft | deprecated

Examples

standard-backend-development-spring-boot-security-active.md
principle-frontend-development-nextjs-principles-active.md
practice-security-testing-penetration-testing-active.md

Configuration

Environment Variables

Customize server behavior with environment variables:

# Change server port (default: 3000)
$env:PORT=3001; npm start

# Change standards directory (default: ./standards)
$env:STANDARDS_DIR="C:\path\to\standards"; npm start

TypeScript Configuration

The project uses strict TypeScript settings defined in tsconfig.json:

• ES2022 target
• ESM modules
• Strict type checking enabled
• Source maps for debugging

Contributing

We welcome contributions to improve the Engineering Standards MCP Server!

Getting Started

1. Fork the repository

2. Create a feature branch:

   git checkout -b feature/your-feature-name
   

3. Make your changes with proper type annotations

4. Test your changes:

   npm start
   # Verify all tools work correctly
   

5. Commit your changes:

   git add .
   git commit -m "Add: your feature description"
   

6. Push to your fork:

   git push origin feature/your-feature-name
   

7. Open a Pull Request with a clear description of changes

Development Guidelines

• Follow existing code style and TypeScript patterns
• Add Zod schemas for new validation requirements
• Update tool descriptions when modifying functionality
• Test with MCP Inspector before submitting
• Keep service layers decoupled and focused

Adding New Tools

1. Create tool file in src/tools/
2. Define input schema in src/schemas/metadata.ts
3. Register tool in src/index.ts
4. Update constants in src/constants.ts
5. Add documentation to this README

License

This project is licensed under the MIT License.

MIT License Summary

Permission is granted to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the software, subject to including the copyright notice and permission notice in all copies.

See the full license text: MIT License

Author

New York Life - Technology Division

Project Stats

• Lines of Code: ~3,000+
• Services: 4 core service layers
• Tools: 6 MCP-compliant tools
• Type Definitions: 12 TypeScript interfaces
• Validation Schemas: 7 Zod schemas
• Dependencies: 192 packages (0 vulnerabilities)
• Sample Standards: 2 complete examples included

Additional Resources

• Quick Start Guide - Detailed setup and usage instructions
• Model Context Protocol - Official MCP documentation
• MCP SDK - TypeScript SDK repository

Support

For issues, questions, or contributions, please contact the New York Life Technology Division team or open an issue in the repository 2. Follow QUICK_START.md for setup 3. Connect your preferred MCP client 4. Start adding your organization's standards

Migration

To migrate legacy standards to the new naming scheme (and normalize type values to singular form), use the migration script:

# Dry-run (preview changes)
npm run migrate

# Apply changes (rename files & update frontmatter)
npm run migrate:apply

---

Ready to use! 🚀