Codebase Knowledge Graph MCP Server

This server provides a Model Context Protocol (MCP) interface specifically designed to interact with a knowledge graph representing a software codebase. It allows storing and retrieving rich, structured information about code entities (classes, functions, files, etc.), their relationships (calls, imports, implements, etc.), and associated qualitative observations (such as design decisions, pattern usage, change rationale, comments, and more).

The goal is to build a comprehensive, queryable representation of the codebase that goes beyond static analysis, capturing architectural insights and development context.

Server Components

• server.js: The main Node.js script that runs the MCP server.

• memory.json: The default file used to persist the knowledge graph data.

Setup and Configuration

1. Install Dependencies:

   npm install

2. Run the Server:

   node server.js

   The server will listen for MCP requests on standard input/output.

3. Persistence Configuration:

   • The knowledge graph is persisted in a file named memory.json by default, located in the same directory as server.js.

   • The file uses the JSON Lines (JSONL) format, where each line is a separate JSON object representing either an entity or a relation.

   • You can specify a custom path for the persistence file by setting the MEMORY_FILE_PATH environment variable before running the server:

   # Example using a custom path (Linux/macOS)
   export MEMORY_FILE_PATH=/path/to/your/custom-graph.jsonl
   node server.js
   
   # Example using a custom path (Windows PowerShell)
   $env:MEMORY_FILE_PATH = "C:\path\to\your\custom-graph.jsonl"
   node server.js

Knowledge Graph Schema

The graph stored and managed by this server consists of three primary components: Entities, Relations, and Observations. Entities represent the core elements (code constructs, project), Relations define connections between them, and Observations attach qualitative information or metadata.

The detailed structure of these components, as defined in server.js, is as follows:

Entity

Represents a distinct element within the codebase or project.

• name (string, required): Unique identifier (e.g., function name, class name, file path).

• entityType (string, required): Type of entity (e.g., 'class', 'function', 'module', 'variable', 'file', 'project').

• language (string, optional): Programming language (e.g., 'javascript', 'python').

• filePath (string, optional): Relative path to the file containing the entity.

• startLine (number, optional): Starting line number (1-indexed).

• endLine (number, optional): Ending line number (1-indexed).

• signature (string, optional): For functions/methods: parameter list, return type.

• summary (string, optional): Brief description (e.g., from docstring).

• accessModifier ('public' | 'private' | 'protected', optional): Language-specific access control.

• isStatic (boolean, optional): Language-specific static indicator.

• isAsync (boolean, optional): Language-specific async indicator.

• namespace (string, optional): Module or namespace.

• tags (string[], optional): User-defined tags for categorization.

• observations (Observation[], required): Array of Observation objects associated with this entity (initialized as empty array if not provided).

• metadata (Record<string, any>, optional): Other custom or tool-specific data.

ProjectEntity

A specific type of Entity (entityType: 'project') used to store high-level information about the project itself.

• name (string, required): Unique name/identifier for the project (e.g., 'my-web-app').

• entityType ('project', required): Must be 'project'.

• description (string, optional): High-level description of the project.

• technologies (string[], optional): List of key technologies used (e.g., ['React', 'Node.js', 'PostgreSQL']).

• architectureStyle (string, optional): Overall architecture (e.g., 'Microservices', 'Monolith', 'Serverless').

• repositoryUrl (string, optional): URL of the code repository.

• observations (Observation[], required): Relevant observations for the project itself (e.g., high-level design decisions, roadmap links).

• metadata (Record<string, any>, optional): Other custom project-specific data.

Relation

Represents a directed relationship between two Entities.

• from (string, required): Name of the source entity.

• to (string, required): Name of the target entity.

• relationType (string, required): Type of relationship (e.g., 'CALLS', 'IMPLEMENTS', 'IMPORTS', 'CONTAINS').

• filePath (string, optional): File where the relation occurs/is defined.

• line (number, optional): Line number where the relation occurs (1-indexed).

• contextSnippet (string, optional): Small code snippet illustrating the relation.

• metadata (Record<string, any>, optional): Other custom or tool-specific data.

Observation

Represents a piece of qualitative information or metadata attached to an Entity.

• id (string, required): Unique ID for the observation (automatically generated UUID if not provided).

• observationType (string, required): Type of observation. Standard types include:

  • 'design_pattern_use': Describes the use of a design pattern. Recommended metadata: { patternName: string, role?: string }.

  • 'design_decision': Documents a specific design choice. Recommended metadata: { rationale?: string, alternativesConsidered?: string[], decisionMaker?: string, relatedIssue?: string }.

  • 'change_rationale': Explains the reason for a code change. Recommended metadata: { commitHash?: string, author?: string, relatedIssue?: string, summaryOfChange?: string }.

  • 'project_meta': Stores project-level metadata (usually attached to a 'Project' entity). Recommended metadata depends on the specific info (e.g., { repositoryUrl: string, primaryTechnology: string }).

  • Other common types: 'comment', 'todo', 'fixme', 'security_note', 'performance_note'.

• content (string, required): The main text/content of the observation.

• filePath (string, optional): File relevant to the observation.

• line (number, optional): Line number relevant to the observation (1-indexed).

• severity ('high' | 'medium' | 'low' | 'info', optional): Severity level.

• source (string, optional): Origin (e.g., 'static_analysis', 'human_annotator', 'llm', 'code_comment').

• timestamp (string, optional): ISO 8601 timestamp (e.g., new Date().toISOString()).

• author (string, optional): Who/what created the observation.

• relatedEntities (string[], optional): Names of other related entities.

• metadata (Record<string, any>, optional): Other custom data. See recommended fields under observationType for standard types.

API Tools Reference

The server exposes the following tools via the Model Context Protocol (MCP). The input for each tool corresponds to the arguments field within an MCP CallToolRequest.

create_entities

• Purpose: Creates one or more new entities in the knowledge graph. If an entity with the same name already exists, it is ignored.

• Arguments:

  {
    "entities": [ ]
  }

• Output: Returns a JSON string representation of the array of entities that were successfully created.

create_relations

• Purpose: Creates one or more new relations between existing entities. Duplicate relations are ignored.

• Arguments:

  {
    "relations": [ ]
  }

• Output: Returns a JSON string representation of the array of relations that were successfully created.

add_observations

• Purpose: Adds observations to existing entities. Fails if the target entity doesn't exist. Assigns unique IDs if missing. Ignores observations with duplicate IDs for the same entity.

• Arguments:

  {
    "observationsInput": [
      {
        "entityName": "string", 
        "observationsToAdd": [ ]
      }
    ]
  }

• Output: Returns a JSON string representation of results, showing added observations per entity.

delete_entities

• Purpose: Removes entities and connected relations.

• Arguments:

  {
    "entityNames": [ "string" ]
  }

• Output: Confirmation message.

delete_observations

• Purpose: Removes specific observations by ID from entities.

• Arguments:

  {
    "deletions": [
      {
        "entityName": "string",
        "observationIds": [ "string"]
      }
  
    ]
  }

• Output: Confirmation message.

delete_relations

• Purpose: Removes specific relations.

• Arguments:

  {
    "relations": [ 
      { "from": "string", "to": "string", "relationType": "string" }, 
     ]
  }

• Output: Confirmation message.

read_graph

• Purpose: Retrieves the entire graph.

• Arguments: None (or {}).

• Output: JSON string of the graph: { "entities": [...], "relations": [...] }.

search_nodes

• Purpose: Searches entities based on a query string (checks names, types, observations, metadata, etc.).

• Arguments:

  {
    "query": "string"
  }

• Output: JSON string of the filtered graph (matching entities and relations between them).

open_nodes

• Purpose: Retrieves specific entities by name and relations between them.

• Arguments:

  {
    "names": [ "string"]
  }

• Output: JSON string of the filtered graph (requested entities and relations between them).

Usage Examples

Here are examples showing the arguments part of an MCP CallToolRequest for common operations:

1. Creating a Project Entity

Use create_entities with entityType: 'project':

{
  "entities": [
    {
      "name": "my-awesome-library",
      "entityType": "project",
      "description": "A library for doing awesome things.",
      "technologies": ["TypeScript", "Node.js"],
      "architectureStyle": "Monolith",
      "repositoryUrl": "https://github.com/user/my-awesome-library",
      "observations": [] 
    }
  ]
}

2. Creating a Function Entity

Use create_entities with entityType: 'function':

{
  "entities": [
    {
        "name": "calculateTotalAmount(items)",
        "entityType": "function",
        "language": "javascript",
        "filePath": "src/utils/calculations.js",
        "startLine": 25,
        "endLine": 40,
        "signature": "(items: Item[]): number",
        "summary": "Calculates the total amount based on a list of items.",
        "accessModifier": "public",
        "isAsync": false,
        "observations": [],
        "tags": ["core-logic", "billing"]
    }
  ]
}

3. Adding a Design Decision Observation

Use add_observations. Note the structure: observationsInput is an array, containing objects for each entity being updated. Each object specifies entityName and an observationsToAdd array.

{
  "observationsInput": [
    {
      "entityName": "MyCoreClass", 
      "observationsToAdd": [
        {
          "observationType": "design_decision",
          "content": "Decided to use Strategy pattern for handling different output formats.",
          "source": "architect_meeting_notes_2023-10-27",
          "author": "Alice",
          "timestamp": "2023-10-27T10:00:00Z",
          "metadata": {
            "rationale": "Provides flexibility to add new formats without modifying the core class.",
            "alternativesConsidered": ["Factory Method", "Simple if/else"],
            "decisionMaker": "Bob",
            "relatedIssue": "PROJ-123"
          }
        }
      ]
    }
  ]
}

4. Adding a Design Pattern Usage Observation

Use add_observations:

{
  "observationsInput": [
    {
      "entityName": "ConfigurationManager", 
      "observationsToAdd": [
        {
          "observationType": "design_pattern_use",
          "content": "Implemented as a Singleton to ensure single point of access to configuration.",
          "source": "code_review_comment_456",
          "author": "Charlie",
          "metadata": {
            "patternName": "Singleton",
            "role": "unique_instance"
          }
        }
      ]
    }
  ]
}

5. Adding a Change Rationale Observation

Use add_observations:

{
  "observationsInput": [
    {
      "entityName": "calculateTotalAmount(items)", 
      "observationsToAdd": [
        {
          "observationType": "change_rationale",
          "content": "Refactored calculation logic for improved performance.",
          "source": "git_commit_a1b2c3d4", 
          "author": "David",
          "timestamp": "2023-10-26T15:30:00Z",
          "metadata": {
            "commitHash": "a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2",
            "relatedIssue": "PERF-45",
            "summaryOfChange": "Replaced loop with vectorized operation."
          }
        }
      ]
    }
  ]
}

6. Creating a Relation

Use create_relations to link two existing entities (e.g., OrderProcessor calls calculateTotalAmount):

{
  "relations": [
    {
        "from": "OrderProcessor.process()", 
        "to": "calculateTotalAmount(items)", 
        "relationType": "CALLS",
        "filePath": "src/services/OrderProcessor.js",
        "line": 88
    }
  ]
}

Usage with NPX / Client Integration

NPX

This command downloads and runs the latest version of the server:

{
  "mcpServers": {
    "codenexus-knowledge-graph": { 
      "command": "npx",
      "args": [
        "-y",
        "codenexus-mcp" 
      ]
    }
  }
}

(Note: VS Code uses a slightly different structure in settings.json or .vscode/mcp.json)

"mcp": {
  "servers": {
    "codenexus-knowledge-graph": { 
      "command": "npx",
      "args": [
        "-y",
        "codenexus-mcp" 
      ]
    }
  }
}

NPX with custom setting

The server can be configured using the MEMORY_FILE_PATH environment variable to specify a custom location for the knowledge graph data file.

{
  "mcpServers": {
    "codenexus-knowledge-graph": { 
      "command": "npx",
      "args": [
        "-y",
        "codenexus-mcp"
      ],
      "env": {
        "MEMORY_FILE_PATH": "/path/to/your/custom-graph.jsonl"
      }
    }
  }
}

(Note: Example for VS Code settings.json below)

"mcp": {
  "servers": {
    "codenexus-knowledge-graph": { 
      "command": "npx",
      "args": [
        "-y",
        "codenexus-mcp"
      ],
      "env": {
        "MEMORY_FILE_PATH": "/path/to/your/custom-graph.jsonl"
      }
    }
  }
}

License

This project is currently unlicensed. Please add appropriate license information here (e.g., MIT License) and include a LICENSE file if applicable.