Skip to main content

​
Prerequisites

Before you begin, ensure you have:
  • Node.js v22.x - Required for development (use nvm use 22 if you have nvm)
  • Git - For version control
  • A code editor (VS Code recommended)
Important: Always use Node.js v22 for local development, even though package.json allows older versions. If you switch Node versions after installing dependencies, run npm rebuild to recompile native modules.

​
Quick Setup

1

Fork and Clone

Fork the repository on GitHub and clone your fork:
git clone https://github.com/YOUR_USERNAME/docs-mcp-server.git
cd docs-mcp-server
2

Install Dependencies

Install all project dependencies:
npm install
This will also set up Husky git hooks for pre-commit checks.
3

Build the Project

Build both server and web assets:
npm run build
This runs two Vite builds - one for web assets and one for the server.
4

Verify Installation

Run the test suite to verify everything is working:
npm test

​
Development Workflow

​
Running the Server

Start the production build: 
npm start
For development with auto-reload: 
npm run dev
This runs both the server and web asset watchers in parallel.

​
Running the Web Interface

To run just the web interface: 
npm run web

​
Running Tests

Run all tests: 
npm test
Run tests in watch mode: 
npm run test:watch
Run a specific test file: 
npx vitest run src/utils/foo.test.ts
Run with coverage: 
npm run test:coverage
Run only unit tests: 
npm run test:unit
Run only end-to-end tests: 
npm run test:e2e
E2E tests automatically build the project first via the pretest:e2e script.

​
Code Quality Checks

Lint your code: 
npm run lint
Auto-fix lint issues: 
npm run lint:fix
For unsafe auto-fixes (use with caution): 
npm run lint:fix -- --unsafe
Format code: 
npm run format
Type checking: 
npm run typecheck

​
Git Workflow

​
Branch Naming

Use the following branch naming convention: 
<type>/<issue>-<description>
Examples:
  • feat/123-add-cache
  • fix/456-search-bug
  • docs/789-update-readme

​
Commit Message Format

Commit messages are strictly enforced by commitlint. Your commits will fail if the format is incorrect. Format: 
<type>(<scope>): <subject>
Types:
  • feat - New feature
  • fix - Bug fix
  • docs - Documentation changes
  • style - Code style changes (formatting, missing semicolons, etc.)
  • refactor - Code refactoring
  • perf - Performance improvements
  • test - Adding or updating tests
  • build - Build system changes
  • ci - CI/CD changes
  • chore - Other changes (dependencies, config, etc.)
  • revert - Revert a previous commit
Subject Rules:
  • Must be lowercase
  • Must NOT end with a period
  • Keep header under 100 characters
Examples: 
git commit -m "feat(search): add semantic search support"
git commit -m "fix(scraper): handle rate limiting correctly"
git commit -m "docs: update installation guide"
With body: 
git commit -m "feat(embeddings): add azure openai provider

Implement support for Azure OpenAI embeddings API.
Includes configuration validation and error handling."
Scope is optional but recommended. The body and footer should be separated from the header with a blank line.

​
Pre-commit Hooks

Husky runs automatically before each commit to:
  1. Run linting checks
  2. Run type checking
  3. Run all tests
Never bypass pre-commit hooks with --no-verify. These checks ensure code quality and prevent broken code from being committed.

​
Security Guidelines

NEVER commit:
  • Secrets or API keys
  • Credentials or passwords
  • .env files with sensitive data
  • Personal access tokens
  • Any other sensitive information
If you accidentally commit sensitive data, contact a maintainer immediately.

​
Opening a Pull Request

When you’re ready to contribute:
1

Ensure All Checks Pass

Make sure lint, typecheck, and tests all pass:
npm run lint && npm run typecheck && npm test
2

Push Your Branch

Push your feature branch to your fork:
git push origin feat/123-your-feature
3

Create Pull Request

Open a pull request on GitHub with:
  • Clear title describing the change
  • Description of what changed and why
  • Reference to any related issues
  • Screenshots/examples if applicable

​
Getting Help

If you have questions or need help:

​
Next Steps

Code Style Guide

Learn about code conventions and formatting

Testing Guide

Understand the testing strategy

Architecture Patterns

Deep dive into system architecture

Build docs developers (and LLMs) love

Get started for freeTalk to us