Project Knowledge MCP Server

A cross-project knowledge graph for the Model Context Protocol (MCP). Map features across mobile, backend, and admin codebases so your AI agent has full-stack context when testing, writing code, debugging, or adding features.

Quick Start

npx -y project-knowledge-mcp --knowledge-file ./project-knowledge.json

Then add to your MCP settings:

{
  "mcpServers": {
    "project-knowledge": {
      "command": "npx",
      "args": [
        "-y",
        "project-knowledge-mcp",
        "--knowledge-file", "C:\\projects\\project-knowledge.json"
      ],
      "autoApprove": []
    }
  }
}

Table of Contents

• Overview
• Features
• Prerequisites
• Installation & Configuration
• Knowledge File Management
• Tools Reference
• Usage Walkthrough
• Security
• Contributing
• License

Overview

The Problem

When working on a project with multiple codebases — for example, a React Native mobile app, a NestJS backend, and a Next.js admin panel — the AI agent has no awareness of how a single feature flows across all three. This leads to incomplete context, missed dependencies, and breaking changes that could have been caught earlier.

The Solution

This MCP server stores a knowledge graph of your features, mapping each workflow step to the relevant screens, endpoints, controllers, and files in every project. The AI agent can then query this graph to understand end-to-end feature flows, detect cross-project impacts before editing files, and keep type definitions synchronized across codebases.

Features

• Multi-project awareness — register any number of projects (mobile, backend, admin, etc.)
• Feature workflow mapping — define features as ordered steps across all projects
• Auto-scanning — discover NestJS endpoints, Next.js pages, and React Native screens automatically
• Full-text search — search across features, endpoints, files, and screens
• Cross-reference lookup — given a file path, find which features reference it
• Rich context — retrieve all endpoints, screens, and files for a feature at a specific workflow step
• Breaking change detection — before editing a file, see which other projects will be affected
• Type/schema synchronization — map equivalent types across projects (e.g., ProductCreateDto ↔ ProductFormSchema)
• Architecture exploration — browse any project's directory tree with keyword filtering and content highlighting
• Health validation — verify that all registered file paths still exist; auto-detect stale entries
• Persistent knowledge — auto-saves to a JSON file after every mutation; can be git-tracked and shared
• 100% dynamic — all configuration via CLI arguments and runtime tools; no source code edits required

Prerequisites

• Node.js >= 18
• npm >= 9 (or pnpm / yarn equivalent)
• An MCP-compatible client (e.g., VS Code with Cline, any AI-powered IDE)

Installation & Configuration

Install from npm (recommended)

npm install --save-dev project-knowledge-mcp

Or run directly without installing:

npx -y project-knowledge-mcp --knowledge-file ./project-knowledge.json

Build from Source

git clone https://github.com/punic-pillars/project-knowledge-mcp.git
cd project-knowledge-mcp
npm install
npm run build

CLI Flags

All configuration is provided via CLI arguments. No environment variables or configuration files are required.

MCP Client Configuration

Basic setup — register projects at runtime via tools:

{
  "mcpServers": {
    "project-knowledge": {
      "command": "npx",
      "args": [
        "-y",
        "project-knowledge-mcp",
        "--knowledge-file", "C:\\projects\\project-knowledge.json"
      ],
      "autoApprove": []
    }
  }
}

Bootstrap setup — pre-register projects at startup:

{
  "mcpServers": {
    "project-knowledge": {
      "command": "npx",
      "args": [
        "-y",
        "project-knowledge-mcp",
        "--knowledge-file", "C:\\projects\\project-knowledge.json",
        "--backend-path", "C:\\projects\\backend",
        "--mobile-path", "C:\\projects\\mobile",
        "--admin-path", "C:\\projects\\admin"
      ],
      "autoApprove": []
    }
  }
}

Knowledge File Management

The knowledge file is a plain JSON file that stores all registered projects, feature workflows, and type mappings. Understanding where it lives is essential for maintaining a consistent knowledge graph.

The Shared File Pattern

If your fullstack projects live in separate directories (e.g., backend/, mobile/, admin/), each IDE window starts the MCP server from a different working directory. Without --knowledge-file, each instance creates its own fragment:

backend/
└── project-knowledge.json   ← only backend context

mobile/
└── project-knowledge.json   ← only mobile context

admin/
└── project-knowledge.json   ← only admin context

This defeats the purpose of cross-project awareness. Always use --knowledge-file with an absolute path to point all IDE windows to the same file:

projects/
├── project-knowledge.json   ← single source of truth
├── backend/
├── mobile/
└── admin/

Use the same --knowledge-file path in every IDE window, regardless of which sub-project you have open. All instances read and write to the same file, keeping the knowledge graph complete and consistent.

When the Default Is Safe

The default path (no --knowledge-file) is only safe when you open the monorepo root — the single directory containing all sub-projects:

my-monorepo/              ← open this in your IDE
├── project-knowledge.json   ← created here, covers everything
├── backend/
├── mobile/
└── admin/

If your projects are in separate repositories or directories, always use --knowledge-file.

Sharing with Your Team

Since the knowledge file is plain JSON, you can commit it to version control and share it with your team:

# Track the knowledge graph
git add project-knowledge.json
git commit -m "chore: add project knowledge graph"

# Or keep it local
echo "project-knowledge.json" >> .gitignore

Guideline: One fullstack project = one knowledge file. Use --knowledge-file with an absolute path whenever your projects live in separate directories.

Tools Reference

Project Management

Feature Management

Search & Query

Type/Schema Synchronization

Architecture Exploration

Validation

Persistence

Usage Walkthrough

This walkthrough demonstrates the core workflow using a real multi-project setup (NestJS backend, React Native mobile, Next.js admin panel). Domain names have been anonymized — "products" instead of "stations", "orders" instead of "reports" — but every command shown was run against actual projects.