MCP Server Implementation
Relevant source files
The following files were used as context for generating this wiki page:
The CodeScholar MCP (Model Context Protocol) server is a context-aware system designed to bridge the gap between source code and academic research. It provides AI agents with the ability to analyze codebases, extract technical concepts, and link them to relevant academic papers using a multi-mode search architecture. By implementing the MCP standard, CodeScholar allows tools like Claude to programmatically access a curated library of research metadata, improving the agent's understanding of the theoretical foundations behind specific code implementations.
Sources: server.js:1-12, README.md:1-5, package.json:1-10
Core Architecture
The server is built using Node.js and the @modelcontextprotocol/sdk. It operates primarily over a standard input/output (stdio) transport, allowing it to be integrated into various MCP-compatible clients. The system manages an in-memory index of papers for fast text search and optionally utilizes a Vectra local vector database for semantic search capabilities.
Sources: server.js:15-30, server.js:770-785, package.json:15-20
System Components and Data Flow
The following diagram illustrates the high-level flow of data from a client request through the server's search and analysis logic:
The server integrates JavaScript-based orchestration with specialized Python scripts for heavy-duty tasks like AST analysis and complex applicability scoring.
Sources: server.js:450-550, server.js:620-680, README.md:38-55
Search Mechanisms
CodeScholar implements a dual-mode search architecture to balance performance and accuracy.
1. Text-Based Search
The server maintains an in-memory index (titleIndex) consisting of lowercased titles, abstracts, and author names. This fallback mode uses multi-term matching and relevance scoring based on weights (Title: 3, Abstract: 2, Authors: 1).
Sources: server.js:35-55, server.js:139-180
2. Hybrid Search
When an OPENAI_API_KEY and a pre-built Vectra index are available, the server enables hybrid search. This combines vector similarity (cosine similarity) with keyword matching to provide semantic depth.
Sources: server.js:60-135, README.md:58-65
| Search Component | Description | Scoring Logic |
|---|---|---|
| Vector Search | Semantic similarity via OpenAI embeddings. | Cosine similarity scaled by 10. |
| Text Search | Keyword matching across metadata. | Weighted sums + citation bonuses. |
| Hybrid Merger | Deduplicates and combines scores. | vector_score + text_score. |
Sources: server.js:95-135
MCP Toolset
The server exposes 7 distinct tools to the MCP client, enabling a range of discovery and analysis workflows.
Sources: server.js:300-440, README.md:7-12
Tool Definitions
| Tool Name | Primary Purpose | Key Parameters |
|---|---|---|
search_papers | Direct keyword or semantic search. | query, limit, year, min_citations |
analyze_code | Extract concepts from local files via AST. | file_path, directory, search_library |
link_papers_to_code | Full pipeline: analyze, query, search, and score. | file_path, max_papers, min_score |
discover_papers | Search external sources (arXiv/Semantic Scholar). | query, sources, max_results |
get_paper_details | Retrieve full metadata for a specific paper ID. | paper_id, doi |
Sources: server.js:305-440
Code-to-Research Pipeline
The link_papers_to_code tool represents the flagship feature of the implementation. It executes a multi-step sequence to find the research foundation of a piece of code:
Sources: server.js:615-730, README.md:15-20
External Service Integration
While the primary library is stored locally in unified_library.json, the server can bridge to external research databases.
Discovery Logic
The discover_papers tool invokes Python-based source wrappers (arxiv_source.py and semantic_scholar_source.py). It specifically filters out results that are already present in the local library by checking DOIs and performing fuzzy title matching.
Sources: server.js:560-610, README.md:46-50
Concept Extraction
Concept extraction uses a pattern-based matching system in the Node.js layer for quick analysis, while the analyze_code tool leverages a more robust AST-based parser in Python for Python, JavaScript, and TypeScript files.
Sources: server.js:460-500, server.js:735-770, README.md:10-12
Library and Knowledge Management
The server expects a structured knowledge base typically generated by the generate_knowledge_base.py script. This script transforms raw metadata into a 3-layer architecture:
- Problems: Decision matrices for specific problem types.
- Techniques: Implementation-focused algorithm cards.
- Papers: Evidence-based metadata with DOI and benchmarks.
Sources: scripts/generate_knowledge_base.py:15-35, knowledge/papers/devops-integration-with-capability-model-maturity-integration-a-systematic-mappi.json:1-15
Paper Metadata Structure
Every paper entry in the system follows a strict schema to ensure compatibility with search and scoring tools:
- Identification: UUID, DOI, and DOI URLs.
- Classification: Problem type, domain, and technique categories.
- Content: Summary, key contribution, and method (approach/algorithm steps).
- Implementation: Implementation guides, dependencies, and "gotchas".
Sources: server.js:205-230, knowledge/papers/devops-integration-with-capability-model-maturity-integration-a-systematic-mappi.json:30-70
The CodeScholar MCP server provides a sophisticated infrastructure for research-driven development. By combining local vector search, AST-based code analysis, and a tiered knowledge architecture, it enables AI agents to provide developers with deep theoretical context and proven implementation patterns directly within their coding environment.
Sources: README.md:68-80, server.js:780-790