analyze-codebase-for-mcp

Files (1)

• SKILL.md

SKILL.md (first lines)

# Analyze Codebase for MCP

Scan a codebase to discover functions, REST endpoints, CLI commands, and data access patterns that are good candidates for MCP tool exposure, then produce a structured tool specification document.

## When to Use

- Planning an MCP server for an existing project and need to know what to expose
- Auditing a codebase before wrapping it as an AI-accessible tool surface
- Comparing what a codebase can do versus what is already exposed via MCP
- Generating a tool specification document to hand off to `scaffold-mcp-server`
- Evaluating whether a third-party library is worth wrapping as MCP tools

## Inputs

- **Required**: Path to the codebase root directory
- **Required**: Target language(s) of the codebase (e.g., TypeScript, Python, R, Go)
- **Optional**: Existing MCP server code to compare against (gap analysis)
- **Optional**: Domain focus (e.g., "data analysis", "file operations", "API integration")
- **Optional**: Maximum number of tools to recommend (default: 20)

## Procedure

### Step 1: Scan Codebase Structure

1.1. Use `Glob` to map the directory tree, focusing on source directories:
   - `src/**/*.{ts,js,py,R,go,rs}` for source files
   - `**/routes/**`, `**/api/**`, `**/controllers/**` for endpoint definitions
   - `**/cli/**`, `**/commands/**` for CLI entry points
   - `**/package.json`, `**/setup.py`, `**/DESCRIPTION` for dependency metadata

1.2. Categorize files by role:
   - **Entry points**: main files, route handlers, CLI commands
   - **Core logic**: business logic functions, algorithms, data transformers
   - **Data access**: database queries, file I/O, API clients
   - **Utilities**: helpers, formatters, validators

1.3. Count total files, lines of code, and exported symbols to gauge project size.

**Got:** A categorized file inventory with role annotations.

**If fail:** If the codebase is too large (>10,000 files), narrow the scan to specific directories or modules using the domain focus input. If no source files are found, verify the root path and language parameters.

### Step 2: Identify Exposed Functions and Endpoints

2.1. Use `Grep` to find exported functions and public APIs:
   - TypeScript/JavaScript: `export (async )?function`, `export default`, `module.exports`
   - Python: functions not prefixed with `_`, `@app.route`, `@router`
   - R: functions listed in NAMESPACE or `#' @export` roxygen tags
   - Go: capitalized function names (exported by convention)

2.2. For each candidate function, extract:
   - **Name**: function or endpoint name
   - **Signature**: parameters with types and defaults
   - **Return type**: what the function produces
   - **Documentation**: docstrings, JSDoc, roxygen, godoc
   - **Location**: file path and line number

2.3. For REST APIs, additionally extract:
   - HTTP method and route pattern
   - Request body schema
   - Response shape
   - Authentication requirements

2.4. Build a candidate list sorted by potential utility (public, documented, well-typed functions first).

**Got:** A list of 20-100 candidate functions/endpoints with extracted metadata.

**If fail:** If few candidates are found, broaden the search to include internal functions that could be made public. If documentation is sparse, flag this as a risk in the output.

### Step 3: Evaluate MCP Suitability

3.1. For each candidate, assess against MCP tool criteria:

   - **Input contract clarity**: Are parameters well-typed and documented? Can they be described in a JSON Schema?
   - **Output predictability**: Does the function return structured data (JSON-serializable)? Is the return shape consistent?
   - **Side effects**: Does the function modify state (files, database, external services)? Side effects must be clearly labeled.
   - **Idempotency**: Is the operation safe to retry? Non-idempotent tools need explicit warnings.
   - **Execution time**: Will it complete within a reasonable timeout (< 30 seconds)? Long-running operations need async patterns.
   - **Error handling**: Does it throw structured errors or fail silently?

3.2. Score each candidate on a 1-5 scale:
   - **5**: Pure function, typed I/O, documented, fast, no side effects
   - **4**: Well-typed, documented, minor side effects (e.g., logging)
   - **3**: Reasonable I/O contract but needs wrapping (e.g., returns raw objects)
   - **2**: Significant side effects or unclear contract, needs substantial adaptation
   - **1**: Not suitable without major refactoring

3.3. Filter candidates to those scoring 3 or above. Flag score-2 items as "future candidates" requiring refactoring.

**Got:** A scored and filtered candidate list with suitability rationale for each.

**If fail:** If most candidates score below 3, the codebase may need refactoring before MCP exposure. Document the gaps and recommend specific improvements (add types, extract pure functions, wrap side effects).

### Step 4: Design Tool Specifications

4.1. For each selected candidate (score >= 3), draft a tool specification:

```yaml
- name: tool_name
  description: >
    One-line description of what the tool does.
  source_function: module.function_name
  source_file: src/path/to/file.ts:42
  parameters:
    param_name:
      type: string | number | boolean | object | array
      description: What this parameter controls
      required: true | false
      default: value_if_optional
  returns:
    type: string | object | array
    description: What the tool returns
  side_effects:
    - description of any side effect
  estimated_latency: fast | medium | slow
  suitability_score: 5
```

4.2. Group tools into logical categories (e.g., "Data Queries", "File Operations", "Analysis", "Configuration").

From pjt222/agent-almanac, MIT.

More from pjt222/agent-almanac