Metadata-Version: 2.4
Name: carton-mcp
Version: 0.1.80
Summary: CartOn - Cartographic knowledge graph mapping for concept networks
Author: HEAVEN System
Requires-Python: >=3.11
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: fastmcp==2.9.0
Requires-Dist: pydantic==2.10.6
Requires-Dist: heaven-framework>=0.1.14
Requires-Dist: neo4j==6.1.0
Requires-Dist: GitPython==3.1.47
Requires-Dist: langchain-core==0.3.84
Requires-Dist: langchain-text-splitters==0.3.11
Requires-Dist: langchain-community==0.3.31
Requires-Dist: langchain-chroma==0.2.3
Requires-Dist: langchain-openai==0.3.22
Requires-Dist: tiktoken==0.12.0
Requires-Dist: chromadb>=0.4.0
Dynamic: license-file

![](https://raw.githubusercontent.com/sancovp/carton-mcp/refs/heads/main/carton_small.png)
[![Part of STARSYSTEM](https://img.shields.io/badge/Part%20of-STARSYSTEM-blue)](https://github.com/sancovp/starsystem-metarepo)

# Carton MCP

<!-- SCALABLE-PUBLISHING:AUTOGEN START (managed block — do not edit between these markers) -->

![License](https://img.shields.io/badge/license-Other-blue.svg) ![Stars](https://img.shields.io/github/stars/sancovp/carton-mcp.svg?style=social) ![Updated](https://img.shields.io/badge/updated-2026_07_08-lightgrey.svg)

⭐ 1 stars • 🕑 Updated 2026-07-08

[Marketplace](https://github.com/sancovp/sancrev-marketplace) • [Docs](https://sancovp.github.io/aisaac/)

📦 Auto-published from the monorepo • [CHANGELOG](./CHANGELOG.md) • [sancovp/carton-mcp](https://github.com/sancovp/carton-mcp)

<!-- SCALABLE-PUBLISHING:AUTOGEN END -->

A Zettelkasten-style knowledge management system that provides both a **core library** for concept management and an **MCP server** for agent-driven knowledge operations.

## Overview

Carton creates a dual-storage concept management system where ideas are stored as both Neo4j graph nodes and GitHub markdown files. The system auto-discovers relationships from text descriptions, manages missing concepts, and provides sophisticated graph querying capabilities.

This package provides both a **core library** for direct concept management and an **MCP server** for agent consumption.

## Core Library Features

### 🏗️ CartOnUtils - Core Business Logic
- **Neo4j Graph Operations**: Execute read-only Cypher queries on :Wiki namespace
- **Concept Network Analysis**: Get connected concepts with 1-3 hop relationship depth  
- **Missing Concept Management**: Detect, track, and auto-create missing concepts
- **Duplicate Detection**: Find similar concepts using textual similarity analysis
- **GitHub Integration**: Commit concept files and missing_concepts.md to repository

### ⚙️ ConceptConfig - Configuration Management
- **Dual Storage Setup**: Configure both GitHub (PAT, repo) and Neo4j (URI, credentials) 
- **HEAVEN Data Integration**: Uses HEAVEN_DATA_DIR for local concept storage
- **Environment-based Config**: Loads settings from environment variables

### 📝 Add Concept Tool - Content Creation
- **Auto-linking**: Discovers concept mentions in descriptions and creates relationships
- **Relationship Inference**: Creates bidirectional links and inverse relationships
- **File Generation**: Creates structured markdown files in wiki/concepts/ directory
- **Neo4j Integration**: Stores concepts as nodes with normalized properties

## MCP Server Features

### 🛠️ 7 MCP Tools
- **add_concept**: Create concepts with auto-relationship discovery
- **query_wiki_graph**: Execute read-only Cypher queries on :Wiki namespace  
- **get_concept_network**: Explore concept relationships with depth control (1-3 hops)
- **list_missing_concepts**: Show concepts referenced but not yet created
- **calculate_missing_concepts**: Scan all concepts and update missing_concepts.md
- **create_missing_concepts**: Bulk create missing concepts with AI descriptions
- **deduplicate_concepts**: Find similar concepts using similarity thresholds

### 📋 4 MCP Prompts
- **add_user_thought**: Capture user quotes verbatim with topic attribution
- **update_known_concept**: Update existing concepts while preserving relationships
- **update_user_thought_train_emergently**: Track how thoughts evolved into insights
- **sync_after_update_known_concept**: Create sync concepts for version control

## Installation

[Installation instructions pending PyPI publication]

## Architecture

**Dual Storage Model:**
- **GitHub**: Markdown files in `wiki/concepts/` structure with auto-linking
- **Neo4j**: Graph database using `:Wiki` namespace with properties `n` (name), `d` (description), `c` (canonical), `t` (timestamp)

**Auto-Discovery System:**
- Scans concept descriptions for mentions of other concepts
- Creates `relates_to` relationships automatically
- Tracks missing concepts and generates creation templates
- Maintains bidirectional relationships and inverse inference

## Dependencies

- HEAVEN Framework for Neo4j utilities and base tool classes
- Neo4j Python driver for graph database operations
- GitHub integration for version control and wiki generation
- MCP protocol for agent tool exposure

## License

MIT License - see LICENSE file for details.
