Knowledge Graph MCP Server

Knowledge Graph MCP Server

한국어 | English

English

An MCP (Model Context Protocol) server implemented in TypeScript for managing knowledge graphs with entities and relations. Track relationships between entities, record observations over time, and provide powerful search capabilities.

Key Features

• Entity Management: Create, retrieve, and delete entities with name, type, and observations
• Relation Management: Create and delete directional relationships between entities
• Observation System: Add and remove time-based observations about entities
• Search Functionality: Search entities by name, type, or observations
• Persistence: Permanent data storage via JSON files
• Concurrency Control: Safe concurrent operation handling
• MCP Protocol: Compliant with standard MCP protocol

Usage

Configuration with MCP Clients

Add the server to your Kiro or other MCP client configuration file:

{
  "mcpServers": {
    "knowledge-graph": {
      "command": "npx",
      "args": [
        "-y",
        "github:YUChoe/knowledge-graph-mcp-server"
      ]
    }
  }
}

To specify a project path:

{
  "mcpServers": {
    "knowledge-graph": {
      "command": "npx",
      "args": [
        "-y",
        "github:YUChoe/knowledge-graph-mcp-server",
        "C:\\Users\\user\\src\\projectdir"
      ]
    }
  }
}

Storage Location

• With project path specified: /knowledge-graph.json
• Without path specified: ~/knowledge-graph.json (user home directory)

API Documentation

The server provides 9 MCP tools:

1. create_entities

Create new entities.

Parameters:

{
  entities: Array<{
    name: string;           // Unique entity name
    entityType: string;     // Entity type
    observations: string[]; // Initial observations
  }>
}

Example:

{
  "entities": [
    {
      "name": "TypeScript",
      "entityType": "programming-language",
      "observations": [
        "Provides static type system",
        "Superset of JavaScript"
      ]
    }
  ]
}

2. create_relations

Create relationships between entities.

Parameters:

{
  relations: Array<{
    from: string;          // Source entity name
    to: string;            // Target entity name
    relationType: string;  // Relation type (active voice)
  }>
}

3. add_observations

Add observations to existing entities.

Parameters:

{
  observations: Array<{
    entityName: string;  // Entity name
    contents: string[];  // Observations to add
  }>
}

4. delete_entities

Delete entities and all associated relations.

Parameters:

{
  entityNames: string[]  // Array of entity names to delete
}

5. delete_observations

Delete specific observations from entities.

Parameters:

{
  deletions: Array<{
    entityName: string;     // Entity name
    observations: string[]; // Observations to delete
  }>
}

6. delete_relations

Delete specific relations.

Parameters:

{
  relations: Array<{
    from: string;
    to: string;
    relationType: string;
  }>
}

7. read_graph

Read the entire knowledge graph.

Parameters: None

8. search_nodes

Search for entities by name, type, or observations.

Parameters:

{
  query: string  // Search query string
}

9. open_nodes

Retrieve specific entities by name.

Parameters:

{
  names: string[]  // Array of entity names to retrieve
}

Error Handling

All errors are returned with both English and Korean messages:

Error: Entity with name "TypeScript" already exists
"TypeScript" 이름을 가진 엔티티가 이미 존재합니다

Common Error Types

• Duplicate Entity: Entity with the same name already exists
• Entity Not Found: Referenced entity cannot be found
• Invalid Parameters: Required parameters missing or type mismatch
• File System Error: Storage file read/write failure

Development

Run Tests

# Run all tests
npm test

# Test watch mode
npm run test:watch

Project Structure

src/
├── types.ts                    # Type definitions
├── graph-storage.ts            # Storage layer
├── knowledge-graph-manager.ts  # Business logic
├── mcp-server.ts              # MCP server implementation
└── bin/
    └── index.ts               # CLI entry point

tests/
├── unit/                      # Unit tests
├── property/                  # Property-based tests
└── integration/               # Integration tests

Testing Strategy

The project uses a dual testing approach:

• Unit Tests: Verify specific examples and edge cases
• Property-Based Tests: Verify universal properties using fast-check

License

MIT

Contributing

Issues and pull requests are welcome.

한국어

TypeScript로 구현된 MCP(Model Context Protocol) 서버로, 엔티티와 관계로 구성된 지식 그래프를 관리합니다. 엔