Introduction to CodeScholar

Relevant source files

The following files were used as context for generating this wiki page:

• README.md
• server.js
• scripts/generate_knowledge_base.py
• knowledge/README.md
• knowledge/problems/code-quality-assessment.json

CodeScholar is a context-aware academic research Model Context Protocol (MCP) server designed to bridge the gap between source code and academic literature. It analyzes codebases to extract technical concepts and links them to relevant research papers using a hybrid search approach that combines vector embeddings with traditional text keyword matching.

The system serves as a structured knowledge base for AI agents and developers, organizing research into actionable layers: high-level problems, specific techniques with pseudocode, and supporting evidence via peer-reviewed papers.

Sources: README.md:3-5, knowledge/README.md:3-5, scripts/generate_knowledge_base.py:10-14

System Architecture

CodeScholar operates as an MCP server that exposes tools for code analysis and paper discovery. The architecture is divided into a runtime server component and a multi-pass knowledge base generation pipeline.

Core Components

• MCP Server (server.js): The primary interface for AI agents, providing tools for searching the library, analyzing code, and scoring paper applicability.
• Knowledge Base Generator (generate_knowledge_base.py): An offline pipeline that transforms raw paper metadata into a 3-layer structured architecture (Problems, Techniques, Papers).
• Vectra Index: A local vector database used for semantic similarity searches.

Data Flow Overview

The following diagram illustrates how a user request for code analysis results in linked academic research.

3-Layer Knowledge Architecture

CodeScholar organizes information into three distinct layers to facilitate different entry points for users.

Layer	Focus	Purpose
Problems	"I have this kind of problem"	Decision matrices to choose between different techniques.
Techniques	"Here's how to solve it"	Algorithmic details, pseudocode, parameters, and tradeoffs.
Papers	"Here's the evidence"	DOIs, benchmarks, and original methodology for verification.

Sources: scripts/generate_knowledge_base.py:12-14, knowledge/README.md:15-28

Knowledge Generation Pipeline

The knowledge base is generated through a four-pass process:

1. Extraction: Deep knowledge (algorithms, benchmarks) is extracted from papers using LLMs.
2. Clustering (Techniques): Papers are grouped to create technique reference cards.
3. Clustering (Problems): Techniques are mapped to problem types to create decision guides.
4. Mapping: Cross-domain connections are identified to find emergent discoveries.

Sources: scripts/generate_knowledge_base.py:16-21

Search and Analysis Mechanisms

Hybrid Search

CodeScholar implements a hybrid search strategy to ensure both keyword precision and semantic depth.

• Text Search: Uses keyword matching across titles, abstracts, and authors with weighted scoring (Title = 3, Abstract = 2, Author = 1).
• Vector Search: Utilizes OpenAI embeddings stored in a Vectra local index to find papers with similar conceptual meanings even if keywords don't match exactly.

Sources: server.js:134-150, server.js:175-200, README.md:52-56

Applicability Scoring

When linking papers to code, the system calculates a weighted score based on:

1. Concept Overlap: How many detected code concepts match the paper.
2. Text Relevance: Keyword match strength.
3. Recency: Preference for newer research.
4. Citations: Impact factor of the paper.

Sources: README.md:11, server.js:585-610

MCP Tools Reference

The server exposes seven primary tools for interaction via the Model Context Protocol.

Tool Name	Description
link_papers_to_code	Flagship tool; analyzes code and returns ranked, applicable papers.
analyze_code	Extracts algorithms, data structures, and concepts from source files.
search_papers	Executes semantic and keyword searches across the local library.
discover_papers	Fetches new research from external sources (arXiv, Semantic Scholar).
get_paper_details	Retrieves full metadata and access URLs for a specific paper.
find_related_papers	Finds papers based on a list of technical concepts.
get_library_stats	Provides metrics on library coverage and citation distributions.

Sources: server.js:283-380, README.md:8-12

Implementation Details

Data Structures

The system relies on structured JSON files for both the primary library and the generated knowledge cards.

{
  "problem_name": "Code Quality Assessment",
  "you_have_this_if": [
    "The code is difficult to read",
    "Frequent bugs in codebase"
  ],
  "decision_matrix": [
    {
      "technique": "Static Code Analysis",
      "speed": "fast",
      "accuracy": "medium"
    }
  ]
}

Sources: knowledge/problems/code-quality-assessment.json:1-30

Multi-Language Analysis

The concept_extractor.py utility supports AST-based analysis for multiple languages, allowing it to identify complex patterns such as Transformer architectures or optimization_algorithms directly from syntax trees.

Sources: README.md:50, server.js:460-475, scripts/generate_knowledge_base.py:100-115

Conclusion

CodeScholar provides a robust framework for integrating academic rigor into the software development lifecycle. By structuring research into Problems, Techniques, and Papers, and providing an MCP-compatible interface, it enables AI agents and human developers to justify implementation choices with proven research evidence.

Sources: knowledge/README.md:3-10