Skip to content

ARCHITECTURE.md

Latest commit

 

History

History
176 lines (135 loc) · 5.85 KB

ARCHITECTURE.md

File metadata and controls

176 lines (135 loc) · 5.85 KB

Architecture

Overview

Moonverse.ts is a Model Context Protocol (MCP) server that provides AI-powered search over MoonBit documentation and source code using Google's Gemini Interactions API.

Components

1. MCP Server (MoonverseMCPServer)

The main server class that implements the MCP protocol using the @modelcontextprotocol/sdk.

Key Responsibilities:

  • Manage server lifecycle
  • Handle tool registration and requests (two tools: docs and source)
  • Coordinate between file management and query processing
  • Maintain separate caches for documentation and source files

2. File Management

Uses Google's GoogleAIFileManager to upload and manage both documentation and source code files.

Flow:

  1. Scan store/ directory for documentation files (.txt, .md)
  2. Scan source/ directory recursively for source files (.mbt, .md, .json, .txt)
  3. Upload files lazily on first query to Gemini's Interactions API
  4. Store file metadata in separate lists for documentation and source code
  5. Cache uploaded files in memory to avoid re-uploads

3. Query Processing

Handles two types of queries using Gemini's Interactions API with uploaded files as context.

Documentation Queries (query_moonbit_docs):

  • Uses files from store/ directory
  • Focuses on answering based on official documentation
  • Provides user-facing feature information

Source Code Queries (query_moonbit_source):

  • Uses files from source/ directory
  • Focuses on implementation details and API insights
  • Provides information about latest features and internal code

Flow:

  1. Receive query via MCP tool call (query_moonbit_docs or query_moonbit_source)
  2. Initialize appropriate file set (documentation or source) if not already done
  3. Create context-aware prompt
  4. Send to Gemini Interactions API with file references
  5. Return AI-generated response

Data Flow

User (Claude Desktop)
    ↓
MCP Protocol
    ↓
Tool Selection (docs or source)
    ↓
MoonverseMCPServer.handleDocQuery() or handleSourceQuery()
    ↓
Initialize files (first time only)
    ↓
Gemini Interactions API (with file context)
    ↓
AI Response
    ↓
MCP Response
    ↓
User sees answer

File Structure

moonverse.ts/
├── src/
│   └── index.ts              # Main server implementation
├── store/                    # Documentation files
│   ├── Agents.mbt.md
│   ├── ide.md
│   └── llms.txt
├── source/                   # MoonBit core repository (optional)
│   └── (MoonBit source files)
├── dist/                     # Compiled JavaScript
│   ├── index.js
│   └── index.d.ts
├── README.md                 # Project overview
├── USAGE.md                  # Usage guide
├── ARCHITECTURE.md           # This file
├── package.json              # Dependencies and scripts
├── tsconfig.json             # TypeScript configuration
└── claude_desktop_config.example.json  # Example config

Key Technologies

MCP (Model Context Protocol)

  • Protocol for AI assistants to access external tools
  • Uses stdio for communication
  • Supports tools, resources, and prompts
  • This project implements two tools for different query types

Gemini Interactions API

  • Google's AI platform with advanced file handling
  • File upload and management
  • Context-aware generation with multiple files
  • Supports multiple file types including source code

TypeScript

  • Type-safe development
  • ES2020 modules
  • Strict mode for better error checking

Design Decisions

1. Lazy Initialization

Files are only uploaded on the first query to avoid startup delays and API costs. Separate initialization for docs and source.

2. Dual Query System

Two separate tools allow users to explicitly choose between documentation queries (user-facing) and source code queries (implementation details).

3. Recursive File Discovery

The source directory is scanned recursively to handle complex repository structures with nested directories.

4. In-Memory File Cache

Uploaded file metadata is stored in memory in separate lists (docs and source) to avoid re-uploading on subsequent queries within the same session.

5. Extended File Type Support

Beyond just .txt and .md, the system now supports .mbt (MoonBit source) and .json files for comprehensive source code analysis.

3. Error Handling

All errors are caught and returned as MCP responses with isError: true, ensuring the MCP client can handle failures gracefully.

4. ES Modules

Uses ES modules (type: "module") for compatibility with the MCP SDK and modern Node.js practices.

5. Stdio Transport

Uses stdio for MCP communication, making it compatible with Claude Desktop and other MCP clients.

Security Considerations

  1. API Key Protection: API key is read from environment variables, never hardcoded
  2. File System Access: Limited to the store/ directory
  3. Input Validation: All tool inputs are validated using Zod schemas
  4. Error Messages: Generic error messages to avoid leaking sensitive information

Scalability

Current Limitations

  • Files are uploaded on each server start
  • No caching between sessions
  • Single-threaded Node.js process

Future Improvements

  • Persistent file store to avoid re-uploads
  • Support for file search stores API (when available in SDK)
  • Batch file uploads
  • Caching layer for common queries
  • Support for incremental document updates

Testing

Currently, the project requires manual testing with a valid Gemini API key. Future improvements could include:

  • Unit tests for file processing logic
  • Integration tests with mock Gemini API
  • End-to-end tests with MCP client simulator

Monitoring

The server logs important events to stderr:

  • File upload progress
  • Query processing
  • Errors and exceptions

These logs can be captured by the MCP host (e.g., Claude Desktop) for debugging.