project-knowledge-mcp
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@project-knowledge-mcp show me the full workflow for the user login feature across all projects"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
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.jsonThen 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
Install from npm (recommended)
npm install --save-dev project-knowledge-mcpOr run directly without installing:
npx -y project-knowledge-mcp --knowledge-file ./project-knowledge.jsonBuild from Source
git clone https://github.com/punic-pillars/project-knowledge-mcp.git
cd project-knowledge-mcp
npm install
npm run buildCLI Flags
All configuration is provided via CLI arguments. No environment variables or configuration files are required.
Flag | Description | Default |
| Absolute path to the backend project | — |
| Backend framework ( |
|
| Custom name for the backend project |
|
| Absolute path to the mobile project | — |
| Mobile framework |
|
| Custom name for the mobile project |
|
| Absolute path to the admin project | — |
| Admin framework |
|
| Custom name for the admin project |
|
| Absolute path to persist the 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 contextThis 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" >> .gitignoreGuideline: One fullstack project = one knowledge file. Use
--knowledge-filewith an absolute path whenever your projects live in separate directories.
Tools Reference
Project Management
Tool | Description |
| Register a project with name, path, and framework |
| Remove a registered project |
| Auto-discover endpoints, screens, or pages from a project |
Feature Management
Tool | Description |
| Define a feature with its multi-project workflow steps |
| Remove a feature |
| Retrieve full feature details (compact or verbose, with optional health check) |
Search & Query
Tool | Description |
| Search across features, endpoints, files, and screens |
| Find all cross-project references to a file (graph-registered + scan-discovered), plus which features reference it |
| Retrieve cross-project context for a feature or step (with optional impact analysis) |
Type/Schema Synchronization
Tool | Description |
| Register one or more type mappings (accepts single object or array) |
| Find all files across projects that define or reference a type |
| Auto-detect potential type mappings by scanning all projects |
Architecture Exploration
Tool | Description |
| Explore a project's directory tree with optional |
Validation
Tool | Description |
| Check all registered file paths for stale entries; optionally auto-fix with |
Persistence
Tool | Description |
| Confirm the knowledge file path and trigger an explicit save (auto-persist handles this after every mutation) |
| 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_knowledgeChecks 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_knowledgeReturns 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
Available Tools
16 toolscheck_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).
searchA
Search across features, endpoints, files, and screens by keyword. Searches both the in-memory knowledge graph (features, workflow steps, type mappings) AND project file contents on disk. Returns all matches with their context (feature name, step, project, or file path + snippet).
Inputs: query (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
Scored across 16 tools
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.
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.
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.
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
Related MCP Connectors
Hosted code graph over MCP: exact callers, dependencies, and cross-repo blast radius for AI agents.
Codebase knowledge graph — architectural awareness for AI coding agents via MCP
Shared product-knowledge graph for AI agent fleets — vault tools + agent self-signup over MCP.
Give your AI agent a persistent map of your project's structure, dependencies, and bugs.
Related MCP Servers
- AlicenseNot gradedqualityDmaintenanceAI-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.23MIT
- AlicenseNot gradedqualityCmaintenanceProvides 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.4Apache 2.0
- AlicenseNot gradedqualityCmaintenanceEnables AI coding agents to query a codebase as a knowledge graph, providing token-budgeted context, search, and impact analysis via MCP tools.27 PyPIMIT
- AlicenseNot gradedqualityDmaintenanceMCP 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 PyPIMIT