Skip to main content
Glama

Project Knowledge MCP Server

Node.js npm License

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": []
    }
  }
}

Related MCP server: OpenCodeHub MCP Server

Table of Contents


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

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

Available Tools

16 tools
check_type_mappingA

Given a type name, find all files across all projects that define or reference it. Use this BEFORE changing a type to know exactly which files in which projects need updating. For example: check_type_mapping('stationId') returns all files in backend, mobile, and admin that use stationId.

Inputs: typeName (required).

export_knowledgeA

Save the current knowledge base to the configured JSON file. Note: the knowledge base is auto-persisted after every mutation, so this call is not required to save your work. Use it as an explicit confirmation — it returns the file path so you know where the file lives before committing to git.

Inputs: no named parameters.

get_architectureA

Explore a registered project's directory structure as a formatted tree view. Use this to understand the project layout, find relevant files, or navigate the codebase. Supports optional filtering by path keyword, and optional content highlighting to find files containing a specific keyword (marked with ★). When using highlight, set showAll=true to see the full tree with matches marked, or omit showAll (default false) to show only matching files.

Inputs: projectName (required), filter, showAll, highlight.

get_contextA

Get rich cross-project context for a feature at a specific workflow step. Returns all relevant endpoints, screens, pages, and files across all projects. Use this before testing or implementing a feature step. Set analyzeImpact=true to also check for breaking changes across projects. Set verbose=true for full per-step breakdown (default: compact summary).

Inputs: featureName (required), verbose, stepNumber, analyzeImpact.

get_featureA

Get full details of a feature — all workflow steps with cross-project mappings. Use this to understand how a feature works end-to-end before testing or coding. Set includeHealth=true to also run a health check on the feature. Set verbose=true for full workflow step details (default: compact summary).

Inputs: name (required), verbose, includeHealth.

import_knowledgeA

Load knowledge from a JSON file. Can merge with existing data or replace it entirely. When merge=false, the current state is auto-backed up before overwriting. Set preview=true to see a diff of what would change without actually importing.

Inputs: filePath (required), merge, preview.

register_featureA

Define or update a feature with its multi-project workflow steps. Each step maps what happens in mobile, backend, and admin. Steps are ordered — the AI will use this order to understand user flows. Use overwrite=true to replace an existing feature.

Inputs: name (required), workflow (required), description (required), overwrite, +1 more.

register_projectA

Register a project (mobile, backend, admin) so the MCP knows its path and framework. Framework can be 'nestjs', 'nextjs', 'react-native', or 'auto' for auto-detection.

Inputs: name (required), path (required), framework, description.

register_type_mappingsA

Register one or more type mappings between projects. Accepts either a single mapping object OR an array of mappings. For example, if 'StationCreateDto' in the backend corresponds to 'StationFormSchema' in mobile, register that mapping here. Then when you change one, you can check what else needs updating. When registering multiple mappings, this reduces 50+ tool calls to 1, providing massive token savings.

Inputs: mappings (required).

remove_featureB

Remove a feature from the knowledge base.

Inputs: name (required).

remove_projectA

Remove a registered project from the knowledge base.

Inputs: name (required).

reverse_lookupA

Given a file path, find all cross-project references to it — both from the Knowledge Graph and by scanning import/require/type-usage in file contents across all registered projects. Use this before editing a file to understand its full blast radius, even when the graph is incomplete. Returns two labeled buckets: graph-registered (formally tracked) and scan-discovered (found ad hoc). Also shows which features and workflow steps reference this file.

Inputs: filePath (required).

scan_projectA

Auto-discover endpoints (backend), screens (mobile), or pages (admin) from a registered project. Returns discovered items for you to link to features.

Inputs: projectName (required).

suggest_type_mappingsA

Auto-detect potential type mappings by scanning all registered projects for type/interface/class/enum definitions. Finds exact name matches across projects (HIGH confidence) and name-similar matches (MEDIUM confidence) by stripping common prefixes/suffixes like Dto, Schema, Form, Payload, etc. Use this to quickly populate the type mapping registry without manual discovery. Set autoRegister=true to automatically register HIGH confidence matches (exact name matches with exactly 2 occurrences).

Inputs: limit, verbose, typeName, confidence, +2 more.

validate_knowledgeA

Check all registered file paths across projects, features, and type mappings to detect stale entries. Files that have been renamed, moved, or deleted will be flagged as MISSING. Use this periodically to keep the knowledge graph in sync with the actual codebase. Optionally pass a featureName to validate only files related to that specific feature. Set fix=true to automatically remove stale entries (use with caution).

Inputs: fix, featureName.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A3.9/5.0

    Scored across 16 tools

    Disambiguation4/5

    Most tools have clearly distinct purposes, but there is slight overlap between reverse_lookup (find references by file) and check_type_mapping (find references by type), and between suggest_type_mappings (auto-detect) and register_type_mappings (manual registration). However, descriptions clarify the intended use for each.

    Naming Consistency5/5

    All tool names follow a consistent snake_case verb_noun pattern (e.g., register_project, get_feature, validate_knowledge). Even 'reverse_lookup' and 'search' fit a predictable style, making the set easy to navigate.

    Tool Count5/5

    With 16 tools, the set is well-scoped for managing projects, features, type mappings, and knowledge base operations. Each tool serves a distinct function without unnecessary bloat, and the count is appropriate for the domain.

    Completeness4/5

    Core operations for projects, features, and type mappings are covered, including create/update/remove/read. Minor gaps exist: there is no explicit 'list_projects' or 'list_features' tool, requiring reliance on search or memory to enumerate items, but this is workable.

    Maintenance

    ActivityInactive
    ResponsivenessOutdated data

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      D
      maintenance
      AI-native code intelligence graph that builds a persistent knowledge graph of your codebase in Neo4j and exposes it to AI assistants via MCP, enabling contextual code analysis, impact analysis, and dependency tracking.
      23
      MIT
    • A
      license
      Not graded
      quality
      C
      maintenance
      Provides code intelligence for AI coding agents by indexing repositories into a hybrid knowledge graph, enabling agents to query dependencies, impact, and context through 28 MCP tools.
      4
      Apache 2.0
    • A
      license
      Not graded
      quality
      D
      maintenance
      MCP server that builds a dependency graph of your codebase, giving AI agents structural understanding to analyze impact, find context, and make safe modifications across languages and infrastructure.
      21 PyPI
      MIT