# QoutaMCP

MCP server for inspecting and analyzing project structures. Detects languages, frameworks, entry points, and dependencies.

🌐 **Live API**: https://mcp.qouta.id

## Installation

### Via NPX (Recommended)
```bash
npx qoutamcp
```

### Via NPM
```bash
npm install -g qoutamcp
qoutamcp
```

### Manual
```bash
git clone https://github.com/QoutaID/qoutaMcp.git
cd qoutaMcp
npm install
npm start
```

## MCP Client Configuration

### Method 1: Local (via NPX) - Full Filesystem Access
```json
{
  "mcpServers": {
    "qoutaMcp": {
      "command": "npx",
      "args": ["-y", "qoutamcp"]
    }
  }
}
```

### Method 2: Local (Manual Install)
```json
{
  "mcpServers": {
    "qoutaMcp": {
      "command": "node",
      "args": ["C:/path/to/qoutaMcp/index.js"]
    }
  }
}
```

### Method 3: Remote (via SSE) - Cloud Hosted
```json
{
  "mcpServers": {
    "qoutaMcp": {
      "type": "sse",
      "url": "https://mcp.qouta.id/sse"
    }
  }
}
```

> ⚠️ **Note**: Remote mode has limited filesystem access (serverless). For full project inspection, use local mode.

## Remote API Usage

### Health Check
```bash
curl https://mcp.qouta.id/
```

### Call Tools via REST API
```bash
# Detect Stack
curl -X POST https://mcp.qouta.id/ \
  -H "Content-Type: application/json" \
  -d '{"tool": "detect_stack", "params": {"path": "/tmp/myproject"}}'

# Inspect Project
curl -X POST https://mcp.qouta.id/ \
  -H "Content-Type: application/json" \
  -d '{"tool": "inspect_project", "params": {"path": "/tmp/myproject", "maxDepth": 3}}'

# List Key Files
curl -X POST https://mcp.qouta.id/ \
  -H "Content-Type: application/json" \
  -d '{"tool": "list_key_files", "params": {"path": "/tmp/myproject"}}'
```

## Available Tools

### 1. `inspect_project`
Complete project snapshot - the primary tool for understanding a project.

**Input:**
```json
{
  "path": "/path/to/project",
  "maxDepth": 3,
  "includeHidden": false
}
```

**Output:**
```json
{
  "project": {
    "language": ["Node.js", "Python"],
    "type": "Web API",
    "confidence": 0.92
  },
  "frameworks": [
    { "name": "FastAPI", "confidence": 0.95 }
  ],
  "entryPoints": ["main.py"],
  "structureSummary": {
    "app": ["routes", "models"],
    "config": ["settings.py"]
  },
  "dependencies": {
    "primary": ["fastapi", "uvicorn"],
    "dev": ["pytest"]
  },
  "configFiles": [".env.example", "pyproject.toml"]
}
```

### 2. `detect_stack`
Lightweight and fast stack detection.

**Input:**
```json
{
  "path": "/path/to/project"
}
```

**Output:**
```json
{
  "runtime": ["Python"],
  "framework": ["FastAPI"],
  "databaseHints": ["PostgreSQL"],
  "frontend": null
}
```

### 3. `list_key_files`
List key files categorized by purpose.

**Input:**
```json
{
  "path": "/path/to/project"
}
```

**Output:**
```json
{
  "entry": ["main.py"],
  "config": ["pyproject.toml", ".env.example"],
  "docs": ["README.md"]
}
```

## Supported Languages

| Language | Signature Files | Frameworks Detected |
|----------|-----------------|---------------------|
| Node.js/TS | `package.json`, `tsconfig.json` | React, Next.js, Express, Vite, NestJS |
| Python | `requirements.txt`, `pyproject.toml` | Flask, FastAPI, Django, Streamlit |
| PHP | `composer.json` | Laravel, Symfony |
| Go | `go.mod` | Gin, Fiber, Echo |
| Java | `pom.xml`, `build.gradle` | Spring Boot |
| Rust | `Cargo.toml` | Actix, Rocket, Axum |

## Error Handling

All errors are returned as JSON:

```json
{
  "error": {
    "code": "PATH_NOT_FOUND",
    "message": "Specified path does not exist"
  }
}
```

## Self-Hosting

### Run as HTTP/SSE Server

```bash
# Local development
npm run server

# With custom port
PORT=8080 node server.js
```

### Deploy to Railway

1. Push to GitHub
2. Connect Railway to your repo
3. Set start command: `node server.js`
4. Deploy!

### Deploy to Render

1. Create new Web Service
2. Connect to GitHub repo
3. Build command: `npm install`
4. Start command: `node server.js`

### Deploy to Vercel (Serverless)

Already configured! Just connect your GitHub repo to Vercel.

## Links

- 🌐 **Live API**: https://mcp.qouta.id
- 📦 **NPM**: https://www.npmjs.com/package/qoutamcp
- 🐙 **GitHub**: https://github.com/QoutaID/qoutaMcp

## License

ISC