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.

Flag	Description	Default
--backend-path	Absolute path to the backend project	—
--backend-framework	Backend framework (nestjs, nextjs, react-native, or auto)	auto
--backend-name	Custom name for the backend project	backend
--mobile-path	Absolute path to the mobile project	—
--mobile-framework	Mobile framework	auto
--mobile-name	Custom name for the mobile project	mobile
--admin-path	Absolute path to the admin project	—
--admin-framework	Admin framework	auto
--admin-name	Custom name for the admin project	admin
--knowledge-file	Absolute path to persist the knowledge JSON	./project-knowledge.json

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

Tool	Description
register_project	Register a project with name, path, and framework
remove_project	Remove a registered project
scan_project	Auto-discover endpoints, screens, or pages from a project

Feature Management

Tool	Description
register_feature	Define a feature with its multi-project workflow steps
remove_feature	Remove a feature
get_feature	Retrieve full feature details (compact or verbose, with optional health check)

Search & Query

Tool	Description
search	Search across features, endpoints, files, and screens
reverse_lookup	Find all cross-project references to a file (graph-registered + scan-discovered), plus which features reference it
get_context	Retrieve cross-project context for a feature or step (with optional impact analysis)

Type/Schema Synchronization

Tool	Description
register_type_mappings	Register one or more type mappings (accepts single object or array)
check_type_mapping	Find all files across projects that define or reference a type
suggest_type_mappings	Auto-detect potential type mappings by scanning all projects

Architecture Exploration

Tool	Description
get_architecture	Explore a project's directory tree with optional filter (path keyword), highlight (content keyword with ★ marker), and showAll (full tree with matches marked)

Validation

Tool	Description
validate_knowledge	Check all registered file paths for stale entries; optionally auto-fix with fix=true

Persistence

Tool	Description
export_knowledge	Confirm the knowledge file path and trigger an explicit save (auto-persist handles this after every mutation)
import_knowledge	Load knowledge from a JSON file (merge or replace, with preview)

---

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.

Step 1: Register Projects

register_project { name: "backend", path: "C:/projects/backend", framework: "nestjs" }
register_project { name: "mobile", path: "C:/projects/mobile", framework: "react-native" }
register_project { name: "admin", path: "C:/projects/admin", framework: "auto" }

Step 2: Scan Projects

Discover endpoints, screens, and pages automatically:

scan_project { projectName: "backend" }
scan_project { projectName: "mobile" }
scan_project { projectName: "admin" }

The scanners discover 150+ endpoints, 200+ screens, and multiple admin pages across all registered projects.

Step 3: Define a Feature

Register an auth feature — a straightforward flow that touches all three projects:

register_feature {
  name: "auth",
  description: "Authentication flow — login, register, forgot password, email confirmation",
  workflow: [
    {
      step: 1, name: "Login",
      description: "User logs in with email and password",
      mobile: { screen: "LoginScreen", api: "POST /api/v1/auth/email/login" },
      backend: { endpoint: "POST /api/v1/auth/email/login", controller: "AuthController", file: "src/auth/auth.controller.ts" },
      admin: { page: "/login", file: "src/pages/Login" }
    },
    {
      step: 2, name: "Register",
      description: "User registers a new account",
      mobile: { screen: "RegisterScreen", api: "POST /api/v1/auth/email/register" },
      backend: { endpoint: "POST /api/v1/auth/email/register", controller: "AuthController", file: "src/auth/auth.controller.ts" }
    },
    {
      step: 3, name: "Email Confirmation",
      description: "Confirm email address",
      mobile: { api: "POST /api/v1/auth/email/confirm" },
      backend: { endpoint: "POST /api/v1/auth/email/confirm", controller: "AuthController", file: "src/auth/auth.controller.ts" }
    },
    {
      step: 4, name: "Forgot Password",
      description: "Request password reset",
      mobile: { screen: "ForgotPasswordScreen", api: "POST /api/v1/auth/forgot/password" },
      backend: { endpoint: "POST /api/v1/auth/forgot/password", controller: "AuthController", file: "src/auth/auth.controller.ts" }
    },
    {
      step: 5, name: "Reset Password",
      description: "Reset password with token",
      mobile: { screen: "ResetPasswordScreen", api: "POST /api/v1/auth/reset/password" },
      backend: { endpoint: "POST /api/v1/auth/reset/password", controller: "AuthController", file: "src/auth/auth.controller.ts" }
    }
  ],
  test_scenarios: [
    "Login with valid credentials returns token",
    "Login with invalid email returns 401",
    "Register with existing email returns conflict",
    "Forgot password sends email",
    "Reset password with valid token works"
  ]
}

Step 4: Query Features

Compact mode — get a summary:

get_feature { name: "auth" }

Returns: 5 steps, 5 test scenarios, mobile=5 screens, backend=5 endpoints, admin=1 page.

Verbose mode — get full workflow details:

get_feature { name: "auth", verbose: true }

Returns all 5 steps with full mobile screens, backend endpoints, controllers, and file paths.

With health check — verify all registered paths exist:

get_feature { name: "auth", includeHealth: true }

Returns: Health: 5/5 backend ok, mobile=5/5, admin=1/5, 5 test scenarios.

Step 5: Search and Cross-Reference

Search across the knowledge graph:

search { query: "product" }

Returns 100+ results across features, workflow steps, backend mappings, mobile mappings, type mappings, and file contents.

Find cross-project references to a file:

reverse_lookup { filePath: "auth.controller.ts" }

Returns:

• Feature associations: Which features reference this file (steps 1–5 of the auth feature)
• Graph-registered: 5 exact matches (steps 1–5 of the auth feature, all backend), plus the admin Login page
• Scan-discovered: All files across all projects that import or reference auth.controller.ts

Step 6: Type Mappings

Register a cross-project type mapping:

register_type_mappings {
  mapping: {
    typeName: "productId",
    sourceProject: "backend",
    sourceFile: "src/products/infrastructure/persistence/relational/entities/product.entity.ts",
    targetProject: "mobile",
    targetFile: "app/_types/ProductTypes.ts",
    description: "Standardizing productId as numeric INTEGER across all projects"
  }
}

Check what references a type before changing it:

check_type_mapping { typeName: "productId" }

Returns all files across all projects that define or reference productId.

Auto-discover potential type mappings:

suggest_type_mappings { limit: 5, confidence: "high" }

Scans all registered projects and finds exact type name matches — returns suggestions with source and target file paths ready to register.

Step 7: Validate and Export

Validate knowledge health:

validate_knowledge

Checks all registered file paths across all features and type mappings. Returns a report of existing and missing entries.

Confirm persistence:

The knowledge graph is auto-persisted after every mutation — register_project, register_feature, register_type_mappings, and validate_knowledge with fix=true all write to disk immediately. Use export_knowledge to confirm the file path before committing to version control:

export_knowledge

Returns the path to the knowledge file. Git-track this file to share context with your team.

---

Security

• Knowledge file is plain JSON — you control where it is stored and who has access
• No credentials stored — this MCP only stores project paths and feature mappings
• File scanning is read-only — scanners only read files, never modify them

---

Contributing

Contributions are welcome. Please open an issue or pull request for any improvements, bug fixes, or feature requests.

---

License

MIT