Metadata-Version: 2.4
Name: code-knowledge-graph-hv
Version: 1.0.0
Summary: A lightweight knowledge graph engine for codebases with CLI, API, and MCP support
Author: Knowledge Graph Team
License: MIT
Project-URL: Homepage, https://github.com/yourusername/code-knowledge-graph
Project-URL: Repository, https://github.com/yourusername/code-knowledge-graph
Project-URL: Issues, https://github.com/yourusername/code-knowledge-graph/issues
Keywords: knowledge-graph,code-analysis,ast,mcp,cli
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Topic :: Software Development :: Code Generators
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.8
Description-Content-Type: text/markdown
Requires-Dist: typer>=0.9.0
Requires-Dist: fastapi>=0.100.0
Requires-Dist: watchdog>=3.0.0
Requires-Dist: uvicorn[standard]>=0.23.0
Provides-Extra: dev
Requires-Dist: pytest>=7.4.0; extra == "dev"
Requires-Dist: pytest-cov>=4.1.0; extra == "dev"
Requires-Dist: black>=23.7.0; extra == "dev"
Requires-Dist: ruff>=0.0.280; extra == "dev"

# Code Knowledge Graph Engine

A lightweight, production-grade knowledge graph engine for codebases. Build and maintain an always-updated graph of code relationships (functions, classes, imports, calls) and query it via CLI, API, or MCP (Model Context Protocol) for AI-assisted development.

## 🎯 Goals

- **Reduce LLM token usage**: Retrieve only relevant code relationships instead of entire files
- **Always-updated graph**: Auto-update on file changes with built-in watcher
- **Plug-and-play**: Easy integration into any project with a single command
- **Multiple interfaces**: CLI, REST API, and MCP server for AI agents
- **Extensible**: Simple architecture for enterprise customization

## 🏗️ Architecture

```
┌─────────────────────────────────────────────────────────────┐
│                     Code Knowledge Graph                     │
├─────────────────────────────────────────────────────────────┤
│                                                               │
│  ┌─────────────┐    ┌─────────────┐    ┌─────────────┐      │
│  │     CLI     │    │  FastAPI    │    │  MCP Server │      │
│  │  (typer)    │    │   Server    │    │  (stdio)    │      │
│  └──────┬──────┘    └──────┬──────┘    └──────┬──────┘      │
│         │                  │                  │              │
│         └──────────────────┼──────────────────┘              │
│                            │                                 │
│                   ┌─────────▼─────────┐                      │
│                   │   Graph Retriever  │                      │
│                   │   (query engine)   │                      │
│                   └─────────┬─────────┘                      │
│                             │                                 │
│                   ┌─────────▼─────────┐                      │
│                   │  Knowledge Graph   │                      │
│                   │  (nodes + edges)   │                      │
│                   └─────────┬─────────┘                      │
│                             │                                 │
│                   ┌─────────▼─────────┐                      │
│                   │  Graph Builder    │                      │
│                   └─────────┬─────────┘                      │
│                             │                                 │
│                   ┌─────────▼─────────┐                      │
│                   │  Python Parser    │                      │
│                   │    (AST-based)    │                      │
│                   └─────────┬─────────┘                      │
│                             │                                 │
│                   ┌─────────▼─────────┐                      │
│                   │  File Watcher     │                      │
│                   │   (watchdog)      │                      │
│                   └───────────────────┘                      │
│                             │                                 │
│                    ┌────────▼────────┐                       │
│                    │  Python Files   │                       │
│                    └─────────────────┘                       │
│                                                               │
└─────────────────────────────────────────────────────────────┘
```

## 📦 Installation

### From source

```bash
# Clone the repository
git clone https://github.com/yourusername/code-knowledge-graph.git
cd code-knowledge-graph

# Install with pip
pip install .
```

### Development installation

```bash
pip install -e ".[dev]"
```

## 🚀 Quick Start

### 1. Build the knowledge graph

```bash
# Build graph for current directory
kg build

# Build graph for specific directory
kg build /path/to/project

# Exclude certain directories
kg build . --exclude "venv,node_modules,.git"
```

### 2. Query dependencies

```bash
# Query dependencies for a function
kg query my_function

# Query with custom depth
kg query my_function --depth 3

# Save output to file
kg query my_function --output deps.json
```

### 3. Start the watcher (auto-update)

```bash
# Watch current directory
kg watch

# Watch specific directory
kg watch /path/to/project
```

### 4. Check status

```bash
kg status
```

### 5. Search nodes

```bash
# Search for nodes
kg search "user"

# Filter by type
kg search "user" --node-type function
```

## 🌐 API Server

### Start the server

```bash
kg serve --host 0.0.0.0 --port 8000
```

### API Endpoints

#### Health Check
```bash
GET /health
```

#### Get Dependencies
```bash
GET /dependencies?target=function_name&depth=5
```

#### Get Full Graph
```bash
GET /graph
```

#### Get Statistics
```bash
GET /stats
```

#### Search Nodes
```bash
GET /search?query=search_term&node_type=function
```

#### Get Function Calls
```bash
GET /functions/{function_name}/calls
```

#### Get File Imports
```bash
GET /files/{file_path}/imports
```

### Example using curl

```bash
# Get dependencies
curl "http://localhost:8000/dependencies?target=my_function"

# Get stats
curl http://localhost:8000/stats

# Search
curl "http://localhost:8000/search?query=user"
```

## 🔌 MCP Server (Model Context Protocol)

The MCP server allows AI agents (like Windsurf, Claude Desktop) to query the knowledge graph directly.

### Start MCP server

```bash
kg-mcp --graph-path storage/graph.json
```

### MCP Methods

#### `dependencies`
Get upstream and downstream dependencies for a target.

```json
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "dependencies",
  "params": {
    "target": "my_function",
    "depth": 5
  }
}
```

#### `search`
Search for nodes in the graph.

```json
{
  "jsonrpc": "2.0",
  "id": 2,
  "method": "search",
  "params": {
    "query": "user",
    "node_type": "function"
  }
}
```

#### `stats`
Get graph statistics.

```json
{
  "jsonrpc": "2.0",
  "id": 3,
  "method": "stats"
}
```

#### `graph`
Get the complete graph.

```json
{
  "jsonrpc": "2.0",
  "id": 4,
  "method": "graph"
}
```

### Integration with AI Tools

#### Windsurf Configuration

Add to your Windsurf config:

```json
{
  "mcpServers": {
    "knowledge-graph": {
      "command": "kg-mcp",
      "args": ["--graph-path", "storage/graph.json"]
    }
  }
}
```

## 📊 Graph Schema

### Node Types

- **file**: Represents a Python source file
- **function**: Represents a function or method
- **class**: Represents a class

### Edge Types

- **calls**: Function A calls Function B
- **imports**: File A imports File B
- **defines**: File defines Function/Class

### Example Graph

```json
{
  "nodes": {
    "file:main.py": {
      "id": "file:main.py",
      "type": "file",
      "name": "main.py",
      "file_path": "main.py",
      "line_number": 1
    },
    "function:process_data:main.py": {
      "id": "function:process_data:main.py",
      "type": "function",
      "name": "process_data",
      "file_path": "main.py",
      "line_number": 10
    }
  },
  "edges": [
    {
      "source": "file:main.py",
      "target": "function:process_data:main.py",
      "type": "defines"
    }
  ]
}
```

## 🧪 Testing

```bash
# Run tests
pytest

# Run with coverage
pytest --cov=core --cov=api --cov=cli --cov=mcp
```

## 🔧 Configuration

### Storage

The graph is stored in JSON format at `storage/graph.json` by default. You can customize this path:

```bash
kg build . --output /custom/path/graph.json
kg query my_function --graph-path /custom/path/graph.json
```

### Exclude Directories

When building the graph, certain directories are excluded by default:
- `venv`, `env`, `.git`, `__pycache__`, `.pytest_cache`, `node_modules`

You can customize this:

```bash
kg build . --exclude "custom_dir,another_dir"
```

## 🎨 Use Cases

### 1. Code Navigation

Quickly find what functions a specific function calls, or what functions call it.

```bash
kg query authenticate_user
```

### 2. Impact Analysis

Before refactoring, understand the downstream impact of changing a function.

```bash
kg query process_payment --depth 10
```

### 3. Code Review

Understand the relationships in a new codebase.

```bash
kg build /path/to/new/project
kg status
```

### 4. AI-Assisted Development

Provide AI agents with structured context about code relationships instead of raw files.

```json
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "dependencies",
  "params": {"target": "main"}
}
```

## 🔒 Security

- The graph stores file paths and code structure, not actual code content
- No external network calls
- All operations are local

## 🤝 Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

## 📄 License

MIT License - see LICENSE file for details

## 🙏 Acknowledgments

- Built with Python AST for reliable parsing
- Uses watchdog for file system monitoring
- FastAPI for the REST API
- Typer for the CLI
- MCP protocol for AI agent integration

## 📞 Support

For issues, questions, or suggestions, please open an issue on GitHub.
