Skip to content

Semantic Analysis

14-agent AI-powered code analysis via MCP.

Semantic Analysis Overview

Overview

Property Value
Component mcp-server-semantic-analysis
Type MCP Server (Node.js)
Port (Docker) 3848
Startup Time ~2s
Memory ~200MB

14 Intelligent Agents

Orchestration (1)

Agent Function
CoordinatorAgent Orchestrates all agents via workflow definitions

LLM-Powered (10)

Agent Function
SemanticAnalysisAgent Deep code analysis using 3-tier LLM chain
InsightGenerationAgent Generates insights with PlantUML diagrams
QualityAssuranceAgent LLM-powered validation with feedback loops
VibeHistoryAgent Processes conversation files for context
ObservationGenerationAgent Creates UKB-compatible observations
ContentValidationAgent Staleness detection and entity refresh
GitHistoryAgent Commit pattern analysis and theme extraction
WebSearchAgent External research via DuckDuckGo
OntologyClassificationAgent Semantic ontology classification
DocumentationLinkerAgent Links docs to code with semantic matching

Embedding/External (2)

Agent Function
DeduplicationAgent Duplicate detection using embeddings
CodeGraphAgent AST indexing via Memgraph

Non-LLM (1)

Agent Function
PersistenceAgent Writes directly to @fwornle/km-core's GraphKMStore (canonical path: .data/knowledge-graph-migrated/)

MCP Tools

Tool Description
heartbeat Connection health monitoring
test_connection Server connectivity verification
determine_insights AI-powered content analysis
analyze_code Code pattern and quality analysis
analyze_repository Repository-wide architecture analysis
extract_patterns Design pattern identification
create_ukb_entity_with_insight Knowledge base entity creation
execute_workflow Coordinated multi-agent workflows
generate_documentation Automated documentation generation
create_insight_report Detailed analysis reports
generate_plantuml_diagrams Architecture diagram generation
reset_analysis_checkpoint Reset analysis checkpoints
refresh_entity Refresh specific knowledge entity
analyze_code_graph AST-based code analysis

Workflows

Complete Analysis

execute_workflow { "workflow_name": "complete-analysis" }

Steps:

  1. GitHistory.analyze()
  2. VibeHistory.analyze()
  3. Semantic.analyze()
  4. WebSearch.research()
  5. Insights.generate()
  6. Observations.generate()
  7. Ontology.classify()
  8. CodeGraph.index()
  9. DocLinker.analyze()
  10. QA.validate()
  11. Persistence.save() — persistWithKmCore() writes through the shared @fwornle/km-core GraphKMStore
  12. Deduplication.merge() — km-core LayeredDeduplicator (Jaccard → Cosine → LLM) + mergeEntities()
  13. ContentValidation.refresh()

Incremental Analysis

execute_workflow { "workflow_name": "incremental-analysis" }

Faster analysis focusing on recent changes.

Quality Assurance

The QA agent implements feedback loops:

  1. Iteration 1: Standard parameters, initial quality check
  2. Iteration 2: Stricter requirements, rejects generic patterns
  3. Iteration 3: Maximum threshold, requires concrete evidence

Entity Evaluation Criteria:

  • Specificity
  • Actionability
  • Evidence
  • Uniqueness
  • Naming

Configuration

The host-side Claude/Copilot CLI talks to the containerized semantic-analysis server via a lightweight stdio proxy:

{
  "mcpServers": {
    "semantic-analysis": {
      "command": "node",
      "args": ["/path/to/mcp-server-semantic-analysis/dist/stdio-proxy.js"],
      "env": {
        "SEMANTIC_ANALYSIS_SSE_URL": "http://localhost:3848"
      }
    }
  }
}

Usage Examples

# Analyze repository
determine_insights {
  "repository": ".",
  "conversationContext": "Current refactoring work",
  "depth": 10
}

# Execute complete analysis
execute_workflow {
  "workflow_name": "complete-analysis"
}

# Extract patterns
extract_patterns {
  "source": "authentication module",
  "pattern_types": ["design", "security"]
}

Storage

  • Entities: .data/knowledge-graph-migrated/ — canonical km-core GraphKMStore (Graphology + LevelDB). The legacy .data/knowledge-graph/ directory survives as a transitional readable copy; km-core is the unconditional persistence path.
  • Auto-export: .data/knowledge-export/{team}.json — git-tracked, debounced 5s after writes
  • Ontology: imported from @fwornle/km-core/ontology (shared upper layer with the observations API and the OKB)
  • Insights: knowledge-management/insights/

This service is the System B consumer in the three-system km-core architecture; System A (observations API) and System C (OKB) consume the same library.

Health Check

curl http://localhost:3848/health

# View logs
docker compose -f docker/docker-compose.yml logs -f coding-services | grep semantic