Skip to content

MCP Tools

Jump to bottom
pi22by7 edited this page Oct 26, 2025 · 1 revision

In Memoria - MCP Tool Reference Guide

This document provides a comprehensive reference for the tools exposed by the In Memoria Model Context Protocol (MCP) server. AI agents should use this guide to understand how to interact with the codebase intelligence system.

Core Agent Workflow

For optimal performance and context-awareness, AI agents should follow this general workflow when starting a new task:

  1. Get Project Overview: Call get_project_blueprint() to quickly understand the project's structure, technology stack, and key files. This is a low-cost way to get initial bearings.

  2. Ensure Intelligence is Fresh: Call auto_learn_if_needed(). This tool will check if the persisted intelligence is stale or missing and will automatically trigger the learning process if necessary. It's a safe and efficient way to ensure you are working with up-to-date information.

  3. Predict and Search: Use tools like predict_coding_approach() for high-level implementation guidance and search_codebase() to find specific examples or relevant files.

  4. Contribute Back: As you work, use contribute_insights() to record important decisions, new patterns, or bug fixes. This enriches the knowledge base for future sessions.

Tool Reference

The tools are organized into four categories:

  1. Core Analysis Tools
  2. Intelligence Tools
  3. Automation Tools
  4. Monitoring Tools

1. Core Analysis Tools

These tools provide direct, real-time analysis of the codebase without relying on the pre-learned intelligence store. They are useful for inspecting the current state of files.

Source: src/mcp-server/tools/core-analysis.ts

analyze_codebase

Analyzes a directory or a single file to provide a comprehensive overview, including concepts, patterns, and complexity metrics.

Parameters

  • path (string, required): The absolute path to the codebase directory or specific file to analyze.
  • includeFileContent (boolean, optional): If true and the path is a file, the full file content will be included in the response. Defaults to false.

Returns

A JSON object containing the analysis result. The structure differs depending on whether a file or a directory was analyzed.

  • For a directory: 
    {
  "path": "/path/to/project",
  "type": "codebase",
  "languages": ["typescript", "rust"],
  "frameworks": ["React", "Node.js"],
  "complexity": { "cyclomatic": 15.2, "cognitive": 25.0, "lines": 12034 },
  "topConcepts": [ { "name": "UserSerivce", "type": "class", "confidence": 0.9 } ],
  "topPatterns": [ { "type": "naming_camelCase", "description": "...", "frequency": 50 } ],
  "summary": { "totalConcepts": 150, "totalPatterns": 25 }
}
  • For a file: 
    {
  "type": "file",
  "path": "/path/to/project/src/index.ts",
  "language": "typescript",
  "lineCount": 150,
  "size": 4500,
  "concepts": [ { "name": "main", "type": "function", "confidence": 0.8, "line": 10 } ],
  "patterns": [ { "type": "arrow_function", "description": "..." } ],
  "complexity": { "cyclomatic": 5, "cognitive": 8, "lines": 150 }
}

search_codebase

Performs a powerful search within the codebase using semantic (meaning-based), text (keyword-based), or pattern-based queries.

Parameters

  • query (string, required): The search query.
  • type (enum, optional): The type of search. Can be semantic, text, or pattern. Defaults to text.
  • language (string, optional): Filters the search to a specific programming language (e.g., typescript, python).
  • limit (number, optional): The maximum number of results to return. Defaults to 20.

Returns

A JSON object containing the search results.

{
  "results": [
    {
      "file": "src/auth/auth.service.ts",
      "content": "export class AuthService { ... }",
      "score": 0.89,
      "context": "> 10: export class AuthService {
  11:   constructor(private readonly jwtService: JwtService) {}",
      "metadata": {
        "lineNumber": 10,
        "type": "semantic"
      }
    }
  ],
  "totalFound": 1,
  "searchType": "semantic"
}

2. Intelligence Tools

These tools query the persistent knowledge base that In Memoria has built about your project. They provide deep insights, recommendations, and predictions based on learned patterns.

Source: src/mcp-server/tools/intelligence-tools.ts

learn_codebase_intelligence

Triggers the deep learning process to analyze a codebase and build the persistent knowledge base. This is a long-running operation.

Parameters

  • path (string, required): The path to the codebase to learn from.
  • force (boolean, optional): If true, forces re-learning even if up-to-date intelligence already exists. Defaults to false.

Returns

A JSON object summarizing the learning process.

{
  "success": true,
  "conceptsLearned": 245,
  "patternsLearned": 42,
  "insights": [
    "🔍 Phase 1: Analyzing codebase structure...",
    "🧠 Phase 2: Learning semantic concepts...",
    "✅ Extracted 245 semantic concepts",
    "⚡ Learning completed in 45231ms"
  ],
  "timeElapsed": 45231
}

get_project_blueprint

Provides a quick, token-efficient overview of the project's architecture, tech stack, and key files. This is the ideal first tool to call.

Parameters

  • path (string, optional): The path to the project. Defaults to the current working directory.
  • includeFeatureMap (boolean, optional): If true, includes a mapping of features to files. Defaults to true.

Returns

A JSON object containing the project blueprint.

{
  "techStack": ["TypeScript", "React", "Node.js", "Express"],
  "entryPoints": {
    "web": "src/index.tsx",
    "api": "src/server.ts"
  },
  "keyDirectories": {
    "components": "src/components",
    "services": "src/services",
    "auth": "src/auth"
  },
  "architecture": "Component-Based (React)",
  "featureMap": {
    "authentication": ["src/auth/auth.service.ts", "src/auth/Login.tsx"]
  },
  "learningStatus": {
    "hasIntelligence": true,
    "isStale": false,
    "conceptsStored": 245,
    "patternsStored": 42,
    "recommendation": "ready",
    "message": "Intelligence is ready!"
  }
}

get_semantic_insights

Retrieves detailed information about the learned semantic concepts and their relationships.

Parameters

  • query (string, optional): A string to filter concepts by name.
  • conceptType (string, optional): Filter by type (e.g., class, function).
  • limit (number, optional): Maximum number of insights to return. Defaults to 10.

Returns

{
  "insights": [
    {
      "concept": "UserService",
      "relationships": ["implements IUserService", "called_by AuthController"],
      "usage": { "frequency": 95, "contexts": ["src/services/user.service.ts"] },
      "evolution": { "firstSeen": "...", "lastModified": "...", "changeCount": 5 }
    }
  ],
  "totalAvailable": 25
}

get_pattern_recommendations

Gets intelligent coding pattern recommendations based on the current context and problem description.

Parameters

  • problemDescription (string, required): A description of the coding task or problem.
  • currentFile (string, optional): The path to the file currently being edited.
  • selectedCode (string, optional): The code snippet the user has selected.
  • includeRelatedFiles (boolean, optional): If true, suggests other files where similar patterns are used.

Returns

{
  "recommendations": [
    {
      "pattern": "service_layer_pattern",
      "description": "Use a service class to encapsulate business logic.",
      "confidence": 0.92,
      "examples": ["export class UserService { ... }"],
      "reasoning": "Based on 12 similar occurrences in your codebase, especially in the services/ directory."
    }
  ],
  "reasoning": "Found 3 relevant patterns based on your coding history.",
  "relatedFiles": ["src/services/order.service.ts"]
}

predict_coding_approach

Predicts the most likely high-level coding approach a developer would take, based on learned patterns.

Parameters

  • problemDescription (string, required): A description of the coding problem.
  • context (object, optional): Additional context (e.g., { "isApi": true }).
  • includeFileRouting (boolean, optional): If true, includes smart routing to target files.

Returns

{
  "approach": "Create a new controller and service, following the existing REST API pattern.",
  "confidence": 0.88,
  "reasoning": "The problem description mentions 'endpoint', and the project consistently uses a service/controller pattern for APIs.",
  "suggestedPatterns": ["service_layer", "controller_pattern"],
  "estimatedComplexity": "medium",
  "fileRouting": {
    "intendedFeature": "api",
    "targetFiles": ["src/controllers/new.controller.ts", "src/services/new.service.ts"],
    "workType": "feature",
    "suggestedStartPoint": "src/controllers/new.controller.ts",
    "confidence": 0.9
  }
}

get_developer_profile

Retrieves the learned profile of the developer, including preferred patterns and coding style.

Parameters

  • includeRecentActivity (boolean, optional): If true, includes recent focus areas.
  • includeWorkContext (boolean, optional): If true, includes the current work session context.

Returns

{
  "preferredPatterns": [ { "pattern": "async_await", "confidence": 0.98, ... } ],
  "codingStyle": {
    "namingConventions": { "functions": "camelCase", "classes": "PascalCase" },
    "structuralPreferences": ["modular_design"],
    "testingApproach": "unit_testing_with_jest"
  },
  "expertiseAreas": ["typescript", "react", "node.js"],
  "recentFocus": ["authentication", "api_design"]
}

contribute_insights

Allows an AI agent to contribute knowledge back to the database, such as a new bug pattern or an architectural decision.

Parameters

  • type (enum, required): The type of insight. Can be bug_pattern, optimization, refactor_suggestion, or best_practice.
  • content (object, required): The details of the insight.
  • confidence (number, required): The agent's confidence in the insight (0.0 to 1.0).
  • sourceAgent (string, required): An identifier for the AI agent.
  • sessionUpdate (object, optional): An optional update to the current work session.

Returns

{
  "success": true,
  "insightId": "insight_1678886400000",
  "message": "Insight contributed successfully and pending validation."
}

3. Automation Tools

These tools help automate the learning and setup process.

Source: src/mcp-server/tools/automation-tools.ts

auto_learn_if_needed

This is a key tool for seamless agent integration. It checks if the codebase intelligence is missing or stale and automatically triggers the learning process if needed. It can also perform a full project setup.

Parameters

  • path (string, optional): Path to the codebase. Defaults to the current directory.
  • force (boolean, optional): If true, forces re-learning even if data is current. Defaults to false.
  • includeProgress (boolean, optional): If true, streams detailed progress information. Defaults to true.
  • skipLearning (boolean, optional): If true, skips the learning phase. Useful for a quick setup verification. Defaults to false.
  • includeSetupSteps (boolean, optional): If true, the tool will perform a full setup, including project checks and database initialization, and return detailed step-by-step results. Defaults to false.

Returns

A JSON object indicating the action taken.

  • If learning is performed: 
    {
  "action": "learned",
  "conceptsLearned": 245,
  "patternsLearned": 42,
  "filesAnalyzed": 150,
  "timeElapsed": 45231,
  "message": "✅ Learning completed!"
}
  • If learning is skipped: 
    {
  "action": "skipped",
  "reason": "Intelligence data is up-to-date",
  "status": { ... } 
}
  • If setup is performed: 
    {
  "success": true,
  "action": "setup_completed",
  "steps": [ { "step": "project_check", "status": "completed", ... } ],
  "message": "✅ Quick setup completed!"
}

4. Monitoring Tools

These tools provide insights into the health and performance of the In Memoria system itself.

Source: src/mcp-server/tools/monitoring-tools.ts

get_system_status

Retrieves a comprehensive status report of the system, including component health and metrics.

Parameters

  • includeMetrics (boolean, optional): If true, includes detailed performance metrics. Defaults to true.
  • includeDiagnostics (boolean, optional): If true, includes system diagnostics. Defaults to false.

Returns

{
  "success": true,
  "status": {
    "version": "0.5.4",
    "status": "operational",
    "components": { "database": { "status": "healthy" } },
    "intelligence": { "status": "ready", "conceptCount": 245 },
    "performance": { "memory": { "heapUsed": 150 }, ... }
  }
}

get_intelligence_metrics

Gets detailed metrics about the contents of the intelligence database.

Parameters

  • includeBreakdown (boolean, optional): If true, includes detailed breakdowns by type and confidence. Defaults to true.

Returns

{
  "success": true,
  "metrics": {
    "concepts": {
      "total": 245,
      "breakdown": { "byType": { "function": 150, "class": 50 } }
    },
    "patterns": {
      "total": 42,
      "breakdown": { "byType": { "naming": 20, "structural": 10 } }
    },
    "quality": { "averageConfidence": 0.85 }
  }
}

get_performance_status

Retrieves performance metrics, including memory usage, query times, and an optional benchmark.

Parameters

  • runBenchmark (boolean, optional): If true, runs a quick performance benchmark. Defaults to false.

Returns

{
  "success": true,
  "performance": {
    "memory": { "rss": 200, "heapUsed": 150 },
    "system": { "nodeVersion": "v18.16.0", "platform": "darwin-arm64" },
    "database": { "size": { "mb": 15.5 } },
    "benchmark": { "conceptQuery": 50, "patternQuery": 75 }
  }
}

Deprecated Tools (Phase 4 Consolidation)

The following tools were deprecated in version 0.5.x to improve the agent experience. Their functionality has been merged into other tools.

  • get_file_content: Merged into analyze_codebase. To get file content, call analyze_codebase with a file path and set includeFileContent: true.
  • get_learning_status: Merged into get_project_blueprint. The blueprint now includes a learningStatus object.
  • quick_setup: Merged into auto_learn_if_needed. To perform a full setup, call auto_learn_if_needed with includeSetupSteps: true.

Clone this wiki locally