Shipwright MCP Server

A read-only Model Context Protocol (MCP) server that exposes the Shipwright project's engineering standards, controls, checklists, and prompt templates to AI coding assistants.

What this is

An MCP server that makes AI coding assistants project-aware. Instead of producing generic output, assistants connected to this server can retrieve the project's own:

• Engineering standards (responsible AI usage, token optimization, PR review, agent governance)
• Security and governance controls (human-in-the-loop, prompt injection prevention, secrets handling)
• Review checklists (PR review, security, accessibility, architecture, token optimization)
• Prompt templates (implementation plan, debugging, reviews)
• Use-case classification (allowed / restricted / prohibited)
• Agent permission model
• Context packs for specific task types

Why it exists

Generic AI output ignores project standards. This server closes that gap by giving assistants structured access to the lab's own engineering rules and responsible AI workflow controls.

What it exposes

Resources

Every document in /docs is exposed as a resource with a stable ai-lab:// URI:

ai-lab://standard/responsible-ai-usage
ai-lab://standard/token-optimization
ai-lab://control/human-in-the-loop
ai-lab://control/prompt-injection
ai-lab://playbook/ai-assisted-feature-delivery
ai-lab://blueprint/ai-engineering-blueprint

Tools

Tool	Purpose
search_knowledge	Search docs corpus by query, type, or tags
get_standard	Retrieve a specific engineering standard
get_control_set	Get controls for a topic or risk area
get_review_checklist	Get checklist for a review type
get_prompt_template	Retrieve a prompt template from the library
classify_ai_use_case	Classify a use case as allowed / restricted / prohibited
build_context_pack	Build a compact context pack for a coding task
get_agent_permission_model	Return the agent permission level model
get_token_optimization_guidance	Get token optimization guidance by risk level
get_accessibility_review_guidance	Get accessibility review checklist and guidance

Prompts

Prompt	Purpose
implementation_plan	Generate a structured plan before writing code
ai_pr_review	Review a PR diff using project standards
security_review	Identify security vulnerabilities in code
accessibility_review	Review UI components for WCAG 2.2 AA
architecture_review	Evaluate architectural implications of a change
token_optimized_debugging	Debug concisely with minimal token usage
context_pack_request	Generate a context pack for a task

Security model

This server is read-only. It:

• Only reads files from the /docs directory
• Prevents path traversal with an explicit allowlist
• Blocks hidden files, .env, .git, node_modules, and build output
• Only serves .md and .json files
• Never executes document content
• Validates all tool inputs with Zod
• Logs to stderr only (never stdout in STDIO mode)
• Returns safe error messages without leaking internal paths

Forbidden capabilities (not implemented): write_file, edit_file, delete_file, commit_changes, push_changes, run_shell, deploy, send_email, upload_document

Read-only guarantee

The server has no write tools. It cannot modify source files, write documentation, approve code, merge branches, delete files, or deploy software.

Setup

Requirements

• Node.js 20+
• npm or pnpm

Install

npm install

Build

npm run build

Run locally

npm start

The server starts on stdio and waits for MCP client connections.

Dev mode (no build step)

npm run dev

Type check

npm run typecheck

Connect to an MCP client

Claude Desktop / Claude Code

Add to your MCP client configuration:

{
  "mcpServers": {
    "shipwright": {
      "command": "node",
      "args": [
        "/absolute/path/to/Shipwright-MCP-Server/build/index.js"
      ]
    }
  }
}

With a custom docs location:

{
  "mcpServers": {
    "shipwright": {
      "command": "node",
      "args": ["/absolute/path/to/Shipwright-MCP-Server/build/index.js"],
      "env": {
        "DOCS_ROOT": "/path/to/your/docs"
      }
    }
  }
}

Using npm scripts

{
  "mcpServers": {
    "shipwright": {
      "command": "npm",
      "args": ["--prefix", "/absolute/path/to/Shipwright-MCP-Server", "start"]
    }
  }
}

Example queries

Search knowledge for "prompt injection controls"
Get the AI PR review checklist
Build a context pack for a high-risk security review
Classify this use case: "AI agent writes and merges auth middleware"
Retrieve token optimization guidance for debugging
Get accessibility review guidance for a React button component
Get the agent permission model
Retrieve the responsible-ai-usage standard

Environment variables

Variable	Default	Description
DOCS_ROOT	../docs relative to build output	Path to docs corpus
MCP_DEBUG	false	Enable debug logging to stderr

Testing

npm test

Tests cover:

• Safe path resolver (path traversal prevention)
• Frontmatter parser (valid, missing, invalid values)
• Document loader (discovery, URI generation, type inference, graceful fallback)
• Search (scoring, limits, type/tag filters)
• Resource registry (URI mapping, not-found handling)
• search_knowledge tool (input validation, results shape)
• classify_ai_use_case tool (all classification paths)
• build_context_pack tool (rules, warnings, checklists)

Known limitations

• Lexical search only. No vector/semantic search in MVP. Results depend on keyword overlap.
• Static corpus. Documents are loaded at startup. Server restart required to pick up new docs.
• No authentication. Local STDIO transport only; no access control layer.
• No persistence. In-memory index only; no database.
• AI cannot certify compliance. Review findings from this server are informational. Human expert review is always required for security and accessibility compliance claims.

Future roadmap

• Vector embeddings and semantic search
• HTTP/SSE transport for remote use
• MCP registry packaging
• Authentication layer
• Team-specific profiles
• GitHub PR metadata integration
• Accessibility audit workflow integration
• Policy versioning and expert review workflow
• Source-validation dashboard