MCP Project Structure Server

A powerful Model Context Protocol (MCP) server that provides intelligent project structure analysis and code understanding capabilities. This server extracts function signatures, tRPC procedures, and project architecture from JavaScript/TypeScript codebases, making it easier for AI assistants to understand and work with your projects.

🚀 Features

• 🔍 Intelligent Code Analysis: Automatically scans and parses JavaScript/TypeScript files
• 📊 Function Signature Extraction: Extracts detailed function signatures with parameters and return types
• 🔄 tRPC Procedure Detection: Specialized support for tRPC router procedures
• 📁 Project Structure Mapping: Organizes code by file structure for better context
• 🎯 Export-Aware Filtering: Option to focus on exported functions only
• 🚫 File/Folder Blacklisting: Exclude specific files or folders from analysis via command line
• ⚡ Fast Performance: Efficient AST parsing and file scanning
• 🔧 MCP Integration: Seamlessly integrates with any MCP-compatible client

📋 Prerequisites

• Node.js 18.0.0 or higher
• TypeScript 5.0.0 or higher (peer dependency)
• MCP-compatible client (like Cursor, Claude Desktop, etc.)

MCP Configuration (works with any MCP client)

Create or update ~/.cursor/mcp.json:

{
  "mcpServers": {
    "mcp-project-structure": {
      "command": "npx",
      "args": ["-y", "mcp-project-structure", "--workspace", "."],
      "env": {}
    }
  }
}

Using Blacklist to Exclude Files/Folders

You can exclude specific files or folders from analysis using the --blacklist parameter:

{
  "mcpServers": {
    "mcp-project-structure": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-project-structure",
        "--workspace",
        ".",
        "--blacklist",
        "tests,dist,*.test.ts"
      ],
      "env": {}
    }
  }
}

The --blacklist parameter accepts comma-separated patterns:

• Folders: tests, dist/, src/components/ui
• Files: file.ts, *.test.ts
• Glob patterns: **/tests/**, **/*.spec.ts

Patterns are automatically normalized to glob format and merged with the default ignore list (which already excludes node_modules, dist, .next, etc.).

For Development/Testing

When developing or testing the MCP server locally, you can use this configuration:

{
  "mcpServers": {
    "mcp-project-structure-dev": {
      "command": "node",
      "args": [
        "<FULL_PATH_TO_YOUR_PROJECT>/dist/index.js",
        "--workspace",
        ".",
        "--blacklist",
        "tests,*.test.ts"
      ],
      "env": {}
    }
  }
}

Note: Replace <FULL_PATH_TO_YOUR_PROJECT> with the actual absolute path to your project's dist/index.js file. For example:

• Windows: "C:\\CodeProjects_Insync\\_MadeInCursor\\mcp-vectordb-search-docs\\dist\\index.js"
• macOS/Linux: "/Users/username/projects/mcp-project-structure/dist/index.js"

This allows you to test changes to the MCP server without publishing to npm first.

📖 Usage Examples

Example 1: Basic Project Analysis

// The server will automatically scan your project and provide:
// - Function signatures from all TypeScript/JavaScript files
// - tRPC procedure definitions
// - Project structure organized by file paths
// - Export status for each function

Example 2: tRPC Router Analysis

// Input: tRPC router file
export const userRouter = router({
  getUser: publicProcedure
    .input(z.object({ id: z.string() }))
    .query(async ({ input }) => {
      return await db.user.findUnique({ where: { id: input.id } });
    }),
  
  createUser: publicProcedure
    .input(z.object({ name: z.string(), email: z.string() }))
    .mutation(async ({ input }) => {
      return await db.user.create({ data: input });
    })
});

// Output: The server will detect and document:
// - Router: userRouter
//   - getUser(input: { id: string }) => Promise<User>
//   - createUser(input: { name: string, email: string }) => Promise<User>

Example 3: React Component Analysis

// Input: React component file
export function UserProfile({ userId, onUpdate }: UserProfileProps) {
  const { data: user } = useUser(userId);
  
  return (
    <div className="user-profile">
      <h1>{user?.name}</h1>
      <button onClick={() => onUpdate(user)}>Update</button>
    </div>
  );
}

// Output: The server will detect:
// - UserProfile(props: UserProfileProps) => JSX.Element

📊 Output Format

The server generates structured markdown output:

# Function Signatures and tRPC Procedures

Summary:
- Scanned 15 code files
- Found 23 function signatures and 8 tRPC procedures in 12 files

## src/routers/user.ts

### Router: userRouter
- getUser(input: { id: string }) => Promise<User>
- createUser(input: { name: string, email: string }) => Promise<User>

### Other Functions
- validateUserInput(data: unknown) => UserInput

🏗️ Architecture

src/
├── index.ts              # Main MCP server entry point
├── tools.ts              # Tool registration and initialization
└── project-structure/    # Core analysis functionality
    ├── init.ts           # MCP tool registration and markdown generation
    ├── parser.ts         # TypeScript AST parsing and signature extraction
    ├── file-scanner.ts   # File discovery and filtering
    └── test-sample.ts    # Example functions for testing

🔍 How It Works

1. File Discovery: Scans the workspace for .ts, .tsx, .js, .jsx files (excluding blacklisted patterns and default ignores)
2. AST Parsing: Uses TypeScript compiler API to parse each file
3. Signature Extraction: Extracts function signatures, parameters, and return types
4. tRPC Detection: Identifies tRPC procedures and their router context
5. Structure Generation: Organizes findings into a hierarchical markdown document
6. MCP Integration: Exposes the analysis as an MCP tool for AI assistants

Command Line Arguments

• --workspace <path>: Required. The workspace directory to scan (must be an absolute path)
• --blacklist <patterns>: Optional. Comma-separated list of file/folder patterns to exclude from analysis

Example:

npx -y mcp-project-structure --workspace /path/to/project --blacklist "tests,dist,*.test.ts"

🧪 Testing

# Build the project
pnpm run build

# Run in development mode
pnpm run dev

# Start the server
pnpm start

Development Setup

git clone https://github.com/yourusername/mcp-project-structure.git
cd mcp-project-structure
pnpm install
pnpm run dev

🙏 Acknowledgments

• Built with Model Context Protocol
• Powered by TypeScript compiler API
• Inspired by the need for better AI code understanding