Engineering Standards MCP Server

# 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](#features) - [Installation](#installation) - [Usage](#usage) - [Architecture](#architecture) - [Tools](#tools) - [File Naming Conventions](#file-naming-conventions) - [Configuration](#configuration) - [Contributing](#contributing) - [License](#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**: ```powershell cd engineering-standards-mcp-server ``` 2. **Install dependencies**: ```powershell 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**: ```powershell 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): ```powershell npm run dev ``` **Production mode**: ```powershell npm start ``` ### Docker Deployment **Using Docker Compose (Recommended)**: ```powershell docker-compose up -d ``` **Using Docker CLI**: ```powershell # Build the image npm run docker:build # Run the container npm run docker:run ``` For detailed Docker deployment instructions, see [DOCKER.md](DOCKER.md). ### Connecting AI Clients **Claude Desktop**: ```powershell claude mcp add --transport http engineering-standards http://localhost:3000/mcp ``` **MCP Inspector** (for testing): ```powershell npx @modelcontextprotocol/inspector # Connect to: http://localhost:3000/mcp ``` **VS Code** (if supported): ```powershell 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: ```powershell 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: ```powershell # 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**: ```powershell git checkout -b feature/your-feature-name ``` 3. **Make your changes** with proper type annotations 4. **Test your changes**: ```powershell npm start # Verify all tools work correctly ``` 5. **Commit your changes**: ```powershell git add . git commit -m "Add: your feature description" ``` 6. **Push to your fork**: ```powershell 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](https://opensource.org/licenses/MIT) ### 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](QUICK_START.md) - Detailed setup and usage instructions - [Model Context Protocol](https://modelcontextprotocol.io/) - Official MCP documentation - [MCP SDK](https://github.com/modelcontextprotocol/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: ```bash # Dry-run (preview changes) npm run migrate # Apply changes (rename files & update frontmatter) npm run migrate:apply ``` --- **Ready to use!** 🚀