{
  "markdown": "# Project Knowledge MCP Server\n\n[![Node.js](https://img.shields.io/badge/node-%3E%3D18-brightgreen)](https://nodejs.org)\n[![npm](https://img.shields.io/badge/npm-%3E%3D9-blue)](https://npmjs.com)\n[![License](https://img.shields.io/badge/license-MIT-green)](LICENSE)\n\n**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.\n\n---\n\n## Quick Start\n\n```bash\nnpx -y project-knowledge-mcp --knowledge-file ./project-knowledge.json\n```\n\nThen add to your MCP settings:\n\n```json\n{\n  \"mcpServers\": {\n    \"project-knowledge\": {\n      \"command\": \"npx\",\n      \"args\": [\n        \"-y\",\n        \"project-knowledge-mcp\",\n        \"--knowledge-file\", \"C:\\\\projects\\\\project-knowledge.json\"\n      ],\n      \"autoApprove\": []\n    }\n  }\n}\n```\n\n---\n\n## Table of Contents\n\n- [Overview](#overview)\n- [Features](#features)\n- [Prerequisites](#prerequisites)\n- [Installation & Configuration](#installation--configuration)\n- [Knowledge File Management](#knowledge-file-management)\n- [Tools Reference](#tools-reference)\n- [Usage Walkthrough](#usage-walkthrough)\n- [Security](#security)\n- [Contributing](#contributing)\n- [License](#license)\n\n---\n\n## Overview\n\n### The Problem\n\nWhen 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.\n\n### The Solution\n\nThis 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.\n\n---\n\n## Features\n\n- **Multi-project awareness** — register any number of projects (mobile, backend, admin, etc.)\n- **Feature workflow mapping** — define features as ordered steps across all projects\n- **Auto-scanning** — discover NestJS endpoints, Next.js pages, and React Native screens automatically\n- **Full-text search** — search across features, endpoints, files, and screens\n- **Cross-reference lookup** — given a file path, find which features reference it\n- **Rich context** — retrieve all endpoints, screens, and files for a feature at a specific workflow step\n- **Breaking change detection** — before editing a file, see which other projects will be affected\n- **Type/schema synchronization** — map equivalent types across projects (e.g., `ProductCreateDto` ↔ `ProductFormSchema`)\n- **Architecture exploration** — browse any project's directory tree with keyword filtering and content highlighting\n- **Health validation** — verify that all registered file paths still exist; auto-detect stale entries\n- **Persistent knowledge** — auto-saves to a JSON file after every mutation; can be git-tracked and shared\n- **100% dynamic** — all configuration via CLI arguments and runtime tools; no source code edits required\n\n---\n\n## Prerequisites\n\n- **Node.js** >= 18\n- **npm** >= 9 (or pnpm / yarn equivalent)\n- An MCP-compatible client (e.g., VS Code with Cline, any AI-powered IDE)\n\n---\n\n## Installation & Configuration\n\n### Install from npm (recommended)\n\n```bash\nnpm install --save-dev project-knowledge-mcp\n```\n\nOr run directly without installing:\n\n```bash\nnpx -y project-knowledge-mcp --knowledge-file ./project-knowledge.json\n```\n\n### Build from Source\n\n```bash\ngit clone https://github.com/punic-pillars/project-knowledge-mcp.git\ncd project-knowledge-mcp\nnpm install\nnpm run build\n```\n\n### CLI Flags\n\nAll configuration is provided via CLI arguments. No environment variables or configuration files are required.\n\n| Flag | Description | Default |\n|------|-------------|---------|\n| `--backend-path` | Absolute path to the backend project | — |\n| `--backend-framework` | Backend framework (`nestjs`, `nextjs`, `react-native`, or `auto`) | `auto` |\n| `--backend-name` | Custom name for the backend project | `backend` |\n| `--mobile-path` | Absolute path to the mobile project | — |\n| `--mobile-framework` | Mobile framework | `auto` |\n| `--mobile-name` | Custom name for the mobile project | `mobile` |\n| `--admin-path` | Absolute path to the admin project | — |\n| `--admin-framework` | Admin framework | `auto` |\n| `--admin-name` | Custom name for the admin project | `admin` |\n| `--knowledge-file` | Absolute path to persist the knowledge JSON | `./project-knowledge.json` |\n\n### MCP Client Configuration\n\n**Basic setup** — register projects at runtime via tools:\n\n```json\n{\n  \"mcpServers\": {\n    \"project-knowledge\": {\n      \"command\": \"npx\",\n      \"args\": [\n        \"-y\",\n        \"project-knowledge-mcp\",\n        \"--knowledge-file\", \"C:\\\\projects\\\\project-knowledge.json\"\n      ],\n      \"autoApprove\": []\n    }\n  }\n}\n```\n\n**Bootstrap setup** — pre-register projects at startup:\n\n```json\n{\n  \"mcpServers\": {\n    \"project-knowledge\": {\n      \"command\": \"npx\",\n      \"args\": [\n        \"-y\",\n        \"project-knowledge-mcp\",\n        \"--knowledge-file\", \"C:\\\\projects\\\\project-knowledge.json\",\n        \"--backend-path\", \"C:\\\\projects\\\\backend\",\n        \"--mobile-path\", \"C:\\\\projects\\\\mobile\",\n        \"--admin-path\", \"C:\\\\projects\\\\admin\"\n      ],\n      \"autoApprove\": []\n    }\n  }\n}\n```\n\n---\n\n## Knowledge File Management\n\nThe 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.\n\n### The Shared File Pattern\n\nIf 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:\n\n```\nbackend/\n└── project-knowledge.json   ← only backend context\n\nmobile/\n└── project-knowledge.json   ← only mobile context\n\nadmin/\n└── project-knowledge.json   ← only admin context\n```\n\nThis defeats the purpose of cross-project awareness. **Always use `--knowledge-file` with an absolute path** to point all IDE windows to the same file:\n\n```\nprojects/\n├── project-knowledge.json   ← single source of truth\n├── backend/\n├── mobile/\n└── admin/\n```\n\nUse 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.\n\n### When the Default Is Safe\n\nThe default path (no `--knowledge-file`) is only safe when you open the **monorepo root** — the single directory containing all sub-projects:\n\n```\nmy-monorepo/              ← open this in your IDE\n├── project-knowledge.json   ← created here, covers everything\n├── backend/\n├── mobile/\n└── admin/\n```\n\nIf your projects are in separate repositories or directories, always use `--knowledge-file`.\n\n### Sharing with Your Team\n\nSince the knowledge file is plain JSON, you can commit it to version control and share it with your team:\n\n```bash\n# Track the knowledge graph\ngit add project-knowledge.json\ngit commit -m \"chore: add project knowledge graph\"\n\n# Or keep it local\necho \"project-knowledge.json\" >> .gitignore\n```\n\n> **Guideline**: One fullstack project = one knowledge file. Use `--knowledge-file` with an absolute path whenever your projects live in separate directories.\n\n---\n\n## Tools Reference\n\n### Project Management\n\n| Tool | Description |\n|------|-------------|\n| `register_project` | Register a project with name, path, and framework |\n| `remove_project` | Remove a registered project |\n| `scan_project` | Auto-discover endpoints, screens, or pages from a project |\n\n### Feature Management\n\n| Tool | Description |\n|------|-------------|\n| `register_feature` | Define a feature with its multi-project workflow steps |\n| `remove_feature` | Remove a feature |\n| `get_feature` | Retrieve full feature details (compact or verbose, with optional health check) |\n\n### Search & Query\n\n| Tool | Description |\n|------|-------------|\n| `search` | Search across features, endpoints, files, and screens |\n| `reverse_lookup` | Find all cross-project references to a file (graph-registered + scan-discovered), plus which features reference it |\n| `get_context` | Retrieve cross-project context for a feature or step (with optional impact analysis) |\n\n### Type/Schema Synchronization\n\n| Tool | Description |\n|------|-------------|\n| `register_type_mappings` | Register one or more type mappings (accepts single object or array) |\n| `check_type_mapping` | Find all files across projects that define or reference a type |\n| `suggest_type_mappings` | Auto-detect potential type mappings by scanning all projects |\n\n### Architecture Exploration\n\n| Tool | Description |\n|------|-------------|\n| `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) |\n\n### Validation\n\n| Tool | Description |\n|------|-------------|\n| `validate_knowledge` | Check all registered file paths for stale entries; optionally auto-fix with `fix=true` |\n\n### Persistence\n\n| Tool | Description |\n|------|-------------|\n| `export_knowledge` | Confirm the knowledge file path and trigger an explicit save (auto-persist handles this after every mutation) |\n| `import_knowledge` | Load knowledge from a JSON file (merge or replace, with preview) |\n\n---\n\n## Usage Walkthrough\n\nThis 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.\n\n### Step 1: Register Projects\n\n```json\nregister_project { name: \"backend\", path: \"C:/projects/backend\", framework: \"nestjs\" }\nregister_project { name: \"mobile\", path: \"C:/projects/mobile\", framework: \"react-native\" }\nregister_project { name: \"admin\", path: \"C:/projects/admin\", framework: \"auto\" }\n```\n\n### Step 2: Scan Projects\n\nDiscover endpoints, screens, and pages automatically:\n\n```json\nscan_project { projectName: \"backend\" }\nscan_project { projectName: \"mobile\" }\nscan_project { projectName: \"admin\" }\n```\n\nThe scanners discover **150+ endpoints**, **200+ screens**, and multiple admin pages across all registered projects.\n\n### Step 3: Define a Feature\n\nRegister an **auth** feature — a straightforward flow that touches all three projects:\n\n```json\nregister_feature {\n  name: \"auth\",\n  description: \"Authentication flow — login, register, forgot password, email confirmation\",\n  workflow: [\n    {\n      step: 1, name: \"Login\",\n      description: \"User logs in with email and password\",\n      mobile: { screen: \"LoginScreen\", api: \"POST /api/v1/auth/email/login\" },\n      backend: { endpoint: \"POST /api/v1/auth/email/login\", controller: \"AuthController\", file: \"src/auth/auth.controller.ts\" },\n      admin: { page: \"/login\", file: \"src/pages/Login\" }\n    },\n    {\n      step: 2, name: \"Register\",\n      description: \"User registers a new account\",\n      mobile: { screen: \"RegisterScreen\", api: \"POST /api/v1/auth/email/register\" },\n      backend: { endpoint: \"POST /api/v1/auth/email/register\", controller: \"AuthController\", file: \"src/auth/auth.controller.ts\" }\n    },\n    {\n      step: 3, name: \"Email Confirmation\",\n      description: \"Confirm email address\",\n      mobile: { api: \"POST /api/v1/auth/email/confirm\" },\n      backend: { endpoint: \"POST /api/v1/auth/email/confirm\", controller: \"AuthController\", file: \"src/auth/auth.controller.ts\" }\n    },\n    {\n      step: 4, name: \"Forgot Password\",\n      description: \"Request password reset\",\n      mobile: { screen: \"ForgotPasswordScreen\", api: \"POST /api/v1/auth/forgot/password\" },\n      backend: { endpoint: \"POST /api/v1/auth/forgot/password\", controller: \"AuthController\", file: \"src/auth/auth.controller.ts\" }\n    },\n    {\n      step: 5, name: \"Reset Password\",\n      description: \"Reset password with token\",\n      mobile: { screen: \"ResetPasswordScreen\", api: \"POST /api/v1/auth/reset/password\" },\n      backend: { endpoint: \"POST /api/v1/auth/reset/password\", controller: \"AuthController\", file: \"src/auth/auth.controller.ts\" }\n    }\n  ],\n  test_scenarios: [\n    \"Login with valid credentials returns token\",\n    \"Login with invalid email returns 401\",\n    \"Register with existing email returns conflict\",\n    \"Forgot password sends email\",\n    \"Reset password with valid token works\"\n  ]\n}\n```\n\n### Step 4: Query Features\n\n**Compact mode** — get a summary:\n\n```json\nget_feature { name: \"auth\" }\n```\n\nReturns: 5 steps, 5 test scenarios, mobile=5 screens, backend=5 endpoints, admin=1 page.\n\n**Verbose mode** — get full workflow details:\n\n```json\nget_feature { name: \"auth\", verbose: true }\n```\n\nReturns all 5 steps with full mobile screens, backend endpoints, controllers, and file paths.\n\n**With health check** — verify all registered paths exist:\n\n```json\nget_feature { name: \"auth\", includeHealth: true }\n```\n\nReturns: Health: 5/5 backend ok, mobile=5/5, admin=1/5, 5 test scenarios.\n\n### Step 5: Search and Cross-Reference\n\n**Search across the knowledge graph:**\n\n```json\nsearch { query: \"product\" }\n```\n\nReturns 100+ results across features, workflow steps, backend mappings, mobile mappings, type mappings, and file contents.\n\n**Find cross-project references to a file:**\n\n```json\nreverse_lookup { filePath: \"auth.controller.ts\" }\n```\n\nReturns:\n- **Feature associations**: Which features reference this file (steps 1–5 of the auth feature)\n- **Graph-registered**: 5 exact matches (steps 1–5 of the auth feature, all backend), plus the admin Login page\n- **Scan-discovered**: All files across all projects that import or reference `auth.controller.ts`\n\n### Step 6: Type Mappings\n\n**Register a cross-project type mapping:**\n\n```json\nregister_type_mappings {\n  mapping: {\n    typeName: \"productId\",\n    sourceProject: \"backend\",\n    sourceFile: \"src/products/infrastructure/persistence/relational/entities/product.entity.ts\",\n    targetProject: \"mobile\",\n    targetFile: \"app/_types/ProductTypes.ts\",\n    description: \"Standardizing productId as numeric INTEGER across all projects\"\n  }\n}\n```\n\n**Check what references a type before changing it:**\n\n```json\ncheck_type_mapping { typeName: \"productId\" }\n```\n\nReturns all files across all projects that define or reference `productId`.\n\n**Auto-discover potential type mappings:**\n\n```json\nsuggest_type_mappings { limit: 5, confidence: \"high\" }\n```\n\nScans all registered projects and finds exact type name matches — returns suggestions with source and target file paths ready to register.\n\n### Step 7: Validate and Export\n\n**Validate knowledge health:**\n\n```json\nvalidate_knowledge\n```\n\nChecks all registered file paths across all features and type mappings. Returns a report of existing and missing entries.\n\n**Confirm persistence:**\n\nThe 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:\n\n```json\nexport_knowledge\n```\n\nReturns the path to the knowledge file. Git-track this file to share context with your team.\n\n---\n\n## Security\n\n- **Knowledge file is plain JSON** — you control where it is stored and who has access\n- **No credentials stored** — this MCP only stores project paths and feature mappings\n- **File scanning is read-only** — scanners only read files, never modify them\n\n---\n\n## Contributing\n\nContributions are welcome. Please open an issue or pull request for any improvements, bug fixes, or feature requests.\n\n---\n\n## License\n\n[MIT](LICENSE)\n",
  "bytes": 16001,
  "sha": "8c29d0eaff4b7d98cd99d4f7f9e241d453f948cf9ac7997c225acee635e30d39",
  "repo_slug": "punic-pillars/project-knowledge-mcp",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_batook22_project_knowledge_mcp_86db7882/readme"
}