Skip to content

REPOSITORY_STRUCTURE.md

Latest commit

 

History

History
484 lines (367 loc) · 15.5 KB

REPOSITORY_STRUCTURE.md

File metadata and controls

484 lines (367 loc) · 15.5 KB
Raw

Repository Structure Reference

Project: MCP Server for KnowBe4 GraphQL API

Version: 1.0.0

Release Date: 2025-10-14

Author: Simon Tin-Yul Kok

Purpose: Complete reference guide to all folders and files in this repository

📋 Quick Navigation

Root Files

Documentation Files (Essential)

File Purpose Audience
README.md Project overview, quick start, features, tool reference New users, stakeholders
CLAUDE.md Architecture, technical reference, best practices Developers, Claude Code
CHANGELOG.md Version history, feature additions, bug fixes All stakeholders
LICENSE.md MIT License and copyright information Legal, compliance

Configuration Files

File Purpose Notes
.gitignore Git exclusion rules Excludes venv, logs, secrets, cache
.env Environment variables (secrets) NOT COMMITTED - Create from .env.example

Source Code (mcp-server/)

Main application source code for the MCP server.

Core Modules

File Lines Purpose Key Functions
main.py 3018 MCP server entry point, tool definitions, advanced intelligence features (NLP extraction, user preferences, predictive suggestions) initialize_server(), query_graphql(), get_quick_query(), discover_queries(), suggest_query_for_question(), auto_answer(), enhance_error_message(), format_smart_summary(), detect_and_execute_dashboard(), warm_cache_on_startup(), extract_variables_from_question(), generate_follow_up_suggestions()
graphql_tools.py 888 GraphQL execution engine, security controls execute_query(), validate_query(), get_type_info(), list_query_fields()
audit_logger.py 218 Compliance-ready audit logging log_query(), log_security_event()
conversation_logger.py 367 User interaction tracking start_conversation(), log_tool_call()
query_library.py 795 Pre-optimized queries, caching get_query(), QueryCache class

Query Libraries

File Lines Purpose Query Count
extended_queries.py ~400 Extended query templates 35+ queries
advanced_queries.py ~450 Advanced query templates 40+ queries
comprehensive_queries.py ~350 Comprehensive query coverage 20+ queries

Total Pre-optimized Queries: 92+ across all libraries

Tests (tests/)

Comprehensive test suite with 203+ test cases and 82%+ coverage.

Test Files

File Lines Tests Purpose
conftest.py 324 N/A Pytest fixtures, mock schema, test utilities, advanced feature fixtures
test_graphql_tools.py 600 50+ GraphQL validation, PII detection, rate limiting
test_audit_logger.py 400 30+ Audit logging, hashing, JSON Lines format
test_conversation_logger.py 450 35+ Conversation tracking, tool call logging
test_query_library.py 350 30+ Query retrieval, caching, TTL management
test_main.py 665 58 Advanced intelligence features: NLP extraction, user preferences, predictive suggestions
diagnose.py 172 N/A Diagnostic utility for troubleshooting

Test Configuration

File Purpose
pytest.ini Pytest configuration, coverage settings, markers
run_tests.sh Test runner script (all, unit, security, coverage modes)
README.md Complete test suite documentation
QUICKSTART.md Quick reference for running tests

Test Coverage: ~85% overall, 100% security features

Setup (setup/)

Installation dependencies and setup utilities.

File Purpose Contents
requirements.txt Production dependencies fastmcp, gql, aiohttp, python-dotenv
requirements-test.txt Test dependencies pytest, pytest-asyncio, pytest-cov, black, ruff
pyproject.toml Python project metadata Package config, tool settings, dependencies
download_schema.py Schema download utility Downloads GraphQL schema from KnowBe4 API
validate_config.py Configuration validator Validates .env and schema setup

Configuration (config/)

Environment configuration and examples.

File Purpose Committed?
.env.example Environment variable template ✅ Yes
.env Actual secrets and config ❌ NO - Gitignored
schema.json KnowBe4 GraphQL schema ❌ NO - Gitignored (user must download)
schema.json.example Instructions for schema ✅ Yes
mcp.json MCP server configuration example ✅ Yes
claude_desktop_config.json.example Claude Desktop integration config ✅ Yes

Important: Never commit .env or schema.json - they contain secrets and proprietary data.

Documentation (docs/)

Detailed guides and references organized by category.

Setup & Configuration

File Lines Purpose
SETUP_SCHEMA.md ~200 GraphQL schema download and configuration guide
DEPENDENCIES.md 396 Dependency management and security scanning guide

Usage & Reference

File Lines Purpose
QUERY_LIBRARY_USAGE.md 610 Complete query reference with 92+ pre-optimized queries
FIELD_REFERENCE.md 423 GraphQL field reference for all types
ANALYZING_LOGS.md 337 Log analysis guide for audit and conversation logs

Development

File Lines Purpose
TESTING.md ~60 Testing quick reference (redirects to tests/README.md)
REPOSITORY_STRUCTURE.md 462 This file - complete repository structure reference

Security

File Lines Purpose
SECURITY_REVIEW.md ~600 Comprehensive security analysis, fixes, compliance status

Note: Historical documents (ROADMAP.md, COMPREHENSIVE_ANALYSIS_RESULTS.md) removed 2025-10-14 as all phases complete and information integrated into active documentation.

Logs (logs/)

Application logs for audit and conversation tracking.

Directory Structure

logs/
├── audit/                    # Compliance audit logs
│   └── audit_YYYYMMDD.jsonl # Daily JSON Lines audit logs
├── conversation/             # User interaction logs
│   └── conversations_YYYYMMDD.jsonl # Daily conversation logs
└── README.md                 # Log structure documentation

Log Files

Directory Format Purpose Retention
logs/audit/ JSON Lines SOC 2/ISO 27001 compliance logging 90 days (configurable)
logs/conversation/ JSON Lines User interaction tracking for improvements 30 days (configurable)

Log Characteristics:

  • ISO 8601 timestamps (UTC)
  • SHA-256 hashing for sensitive data
  • Immediate flush to disk
  • SIEM-ready format

Hidden/System Files

File/Directory Purpose Committed?
.git/ Git version control metadata ✅ (managed by Git)
venv/ Python virtual environment ❌ Gitignored
__pycache__/ Python bytecode cache ❌ Gitignored
.pytest_cache/ Pytest cache ❌ Gitignored
htmlcov/ Coverage HTML reports ❌ Gitignored
.DS_Store macOS metadata ❌ Gitignored

File Type Summary

Type Count Purpose
Python Source 8 Main application code
Python Tests 6 Test suite (pytest + diagnose utility)
Markdown Docs 15 Documentation (4 root + 8 docs/ + 3 other)
Config Files 6 Configuration templates
Shell Scripts 1 Test runner
JSON Files 3 Configuration examples
Text Files 2 Requirements

Total Project Files: 41 (excluding venv, cache, logs)

Code Metrics

Source Code

Metric Count
Total Source LOC ~6,108
Total Test LOC 3,059
Test:Code Ratio 50%
Documentation Lines ~2,617
Test Functions 203
Pre-optimized Queries 92+

Coverage

Component Coverage
graphql_tools.py ~85%
audit_logger.py ~90%
conversation_logger.py ~85%
query_library.py ~80%
Overall ~85%

Directory Tree

PROJECT-MCP-KnowBe4/
│
├── README.md                      # Project overview and quick start
├── CLAUDE.md                      # Architecture and technical reference
├── CHANGELOG.md                   # Version history
├── LICENSE.md                     # MIT License
├── .gitignore                     # Git exclusions
│
├── mcp-server/                    # Source code
│   ├── main.py                    # MCP server entry
│   ├── graphql_tools.py           # GraphQL engine
│   ├── audit_logger.py            # Audit logging
│   ├── conversation_logger.py     # User tracking
│   ├── query_library.py           # Query cache
│   ├── extended_queries.py        # Extended queries
│   ├── advanced_queries.py        # Advanced queries
│   └── comprehensive_queries.py   # Comprehensive queries
│
├── tests/                         # Test suite
│   ├── conftest.py                # Pytest fixtures
│   ├── pytest.ini                 # Pytest config
│   ├── run_tests.sh               # Test runner
│   ├── README.md                  # Comprehensive test docs
│   ├── QUICKSTART.md              # Quick start
│   ├── test_graphql_tools.py      # GraphQL tests
│   ├── test_audit_logger.py       # Audit tests
│   ├── test_conversation_logger.py # Conversation tests
│   ├── test_query_library.py      # Cache tests
│   ├── test_main.py               # Advanced feature tests
│   └── diagnose.py                # Diagnostics
│
├── setup/                         # Installation
│   ├── requirements.txt           # Prod dependencies
│   ├── requirements-test.txt      # Test dependencies
│   ├── pyproject.toml             # Package metadata
│   ├── download_schema.py         # Schema downloader
│   └── validate_config.py         # Config validator
│
├── config/                        # Configuration
│   ├── .env.example               # Env template
│   ├── schema.json.example        # Schema instructions
│   ├── mcp.json                   # MCP config
│   └── claude_desktop_config.json.example
│
├── docs/                          # Detailed documentation
│   ├── SETUP_SCHEMA.md            # Schema setup guide
│   ├── DEPENDENCIES.md            # Dependency management
│   ├── QUERY_LIBRARY_USAGE.md     # Query reference (92+ queries)
│   ├── FIELD_REFERENCE.md         # GraphQL field reference
│   ├── ANALYZING_LOGS.md          # Log analysis guide
│   ├── TESTING.md                 # Testing quick reference
│   ├── REPOSITORY_STRUCTURE.md    # This file
│   └── SECURITY_REVIEW.md         # Security analysis
│
└── logs/                          # Application logs
    ├── README.md                  # Log structure
    ├── audit/                     # Audit logs
    │   └── audit_YYYYMMDD.jsonl
    └── conversation/              # Conversation logs
        └── conversations_YYYYMMDD.jsonl

Key File Relationships

Development Workflow

1. Setup:
   config/.env.example → .env (create)
   setup/download_schema.py → config/schema.json

2. Development:
   mcp-server/*.py (source code)
   ↓
   tests/*.py (test code)
   ↓
   tests/run_tests.sh (validate)

3. Documentation:
   README.md (overview)
   → docs/SETUP_SCHEMA.md (setup)
   → docs/TESTING.md or tests/README.md (testing)
   → CLAUDE.md (architecture)

4. Deployment:
   config/.env (secrets)
   + config/schema.json (schema)
   + mcp-server/*.py (code)
   → Production deployment

Data Flow

User Request
  ↓
main.py (MCP tools)
  ↓
graphql_tools.py (validation, execution)
  ↓
audit_logger.py (log query)
  ↓
conversation_logger.py (log interaction)
  ↓
logs/ (persist)

Getting Started Guide

For New Developers

  1. Read in order:

    • README.md - Project overview
    • docs/SETUP_SCHEMA.md - Setup instructions
    • CLAUDE.md - Architecture details

  2. Setup environment:

    cp config/.env.example .env
pip install -r setup/requirements.txt
python setup/download_schema.py

  3. Run tests:

    cd tests
./run_tests.sh

For Reviewers

  1. Code review:

    • mcp-server/ - Source code
    • tests/ - Test coverage
    • docs/SECURITY_REVIEW.md - Security analysis

  2. Documentation review:

    • docs/ - Technical guides
    • CHANGELOG.md - Recent changes

For Auditors

  1. Security review:

    • docs/SECURITY_REVIEW.md - Security analysis
    • mcp-server/audit_logger.py - Audit implementation

  2. Compliance:

    • logs/audit/ - Audit trails
    • CLAUDE.md - Security controls

Maintenance Notes

Files to Update When...

Adding a new feature:

  • mcp-server/main.py - Add MCP tool
  • tests/test_*.py - Add tests
  • CHANGELOG.md - Document change
  • README.md - Update features list

Fixing a security issue:

  • mcp-server/graphql_tools.py or relevant file
  • tests/test_*.py - Add regression test
  • docs/SECURITY_REVIEW.md - Update status
  • CHANGELOG.md - Document fix

Updating dependencies:

  • setup/requirements.txt - Update versions
  • setup/requirements-test.txt - Update test deps
  • CHANGELOG.md - Document changes

Adding documentation:

  • docs/ - Add new guide
  • This file (docs/REPOSITORY_STRUCTURE.md) - Update table
  • README.md - Add link if needed

File Naming Conventions

Documentation Files

  • Root docs: UPPERCASE.md (essential only)
  • Subdirectory docs: UPPERCASE_WORDS.md
  • Quick refs: QUICKSTART.md, README.md

Python Files

  • Modules: snake_case.py
  • Tests: test_module_name.py
  • Utilities: verb_noun.py (e.g., download_schema.py)

Configuration Files

  • Examples: filename.example or .env.example
  • Config: .lowercase or lowercase.extension

Quick Reference

Most Important Files

File Why It Matters
README.md First stop for everyone
mcp-server/main.py Server entry point
tests/run_tests.sh Validate everything works
config/.env Secrets and configuration
docs/SECURITY_REVIEW.md Security posture

Most Frequently Modified

File Change Frequency Typical Changes
mcp-server/main.py High Adding new MCP tools
tests/test_*.py High Adding test coverage
CHANGELOG.md Very High Every feature/fix
config/.env Medium Environment updates
README.md Medium Feature documentation

Documentation version: 1.0.0