# Documentary MCP Server

NestJS + PostgreSQL + [@rekog/mcp-nest](https://www.npmjs.com/package/@rekog/mcp-nest) ile proje bazli dokumantasyon olusturan ve listeleyen MCP sunucusu.

## Ozellikler

- **Proje bazli dokumanlar**: Her dokuman bir `projectName` ile gruplanir; backend/frontend gibi farkli agentlar kendi projelerinde calisir.
- **Dokuman olusturma**: Markdown icerik, otomatik **icindekiler (table of contents)** ve slug.
- **Arama**: **Full-text search** (dogal dil) ve **regex** ile icerik arama.
- **Minimal token kullanimi**: `get_document` tool'unda `sectionId` ile tek bir bolum okunabilir.
- **Multi-client destek**: Streamable HTTP transport ile birden fazla agent ayni anda baglanabilir.

## Gereksinimler

- Node.js 18+
- PostgreSQL 14+

## Kurulum

```bash
yarn install
cp .env.example .env
# .env icinde DB_* degerlerini duzenleyin
yarn start:dev
```

- Uygulama: `http://localhost:3000`
- MCP endpoint: `http://localhost:3000/mcp`

## MCP Araclari (Tools)

| Tool | Aciklama |
|------|----------|
| `list_projects` | Tum projeleri listeler (proje adi + dokuman sayisi). Ilk adim olarak kullanin. |
| `create_document` | Belirtilen projede dokuman olusturur. Icerik Markdown; `#`, `##` ile basliklar TOC'e eklenir. |
| `list_documents` | Bir projedeki dokumanlari listeler (id, title, slug, TOC, tarihler). |
| `search_documents` | Proje icinde full-text veya regex arama. Snippet doner. |
| `get_document` | Proje+slug veya id ile tam dokuman icerigi + TOC. `sectionId` ile tek bolum okunabilir. |
| `get_document_toc` | Sadece icindekiler; bolum bazli okumak icin `get_document` ile `sectionId` kullanilir. |

## MCP Resource Template

- **URI**: `mcp://documents/{projectName}/{slug}`
- Tam dokuman: TOC + tum icerik.

Ornek: Backend agent dokumani yazar -> Frontend agent `list_projects` -> `list_documents` -> `get_document_toc` -> `get_document` ile `sectionId` vererek sadece ilgili bolumu okur.

## Ornek kullanim (agent senaryolari)

1. **Backend agent**: `create_document` ile `projectName: "backend-api"`, baslik ve detayli Markdown icerik gonderir.
2. **Frontend agent**: `list_projects` -> `search_documents` (projectName: "backend-api", query: "login") -> `get_document_toc` -> `get_document` ile `sectionId: "login"` vererek sadece ilgili bolumu okur.

## Ortam degiskenleri

| Degisken | Varsayilan | Aciklama |
|----------|------------|----------|
| `PORT` | 3000 | HTTP portu |
| `DB_HOST` | localhost | PostgreSQL host |
| `DB_PORT` | 5432 | PostgreSQL port |
| `DB_USER` | postgres | Kullanici |
| `DB_PASSWORD` | postgres | Sifre |
| `DB_NAME` | documentary_mcp | Veritabani adi |
| `DB_LOGGING` | false | SQL loglama |
| `MCP_API_KEY` | (bos) | Tanimliysa MCP endpoint'i `API_KEY` veya `Authorization: Bearer` header ile korunur |

## Docker ile calistirma

Sunucuyu bilgisayarinizda surekli calisir halde tutmak icin Docker Compose kullanin:

```bash
cp .env.example .env
# Istege bagli: MCP_API_KEY=your-secret-key
docker compose up -d --build
```

- Uygulama: `http://localhost:3000`
- MCP: `http://localhost:3000/mcp`
- Veritabani verisi `postgres_data` volume'da kalir.

Durdurmak: `docker compose down`

## Cursor MCP ayari

### Remote Server (HTTP - onerilen)

Sunucu Docker veya `yarn start:dev` ile calisiyorken Cursor'da **Remote Server** olarak ekleyin. `~/.cursor/mcp.json`:

```json
{
  "mcpServers": {
    "documentary": {
      "url": "http://localhost:3027/mcp"
    }
  }
}
```

`MCP_API_KEY` kullaniyorsaniz `headers` ekleyin:

```json
{
  "mcpServers": {
    "documentary": {
      "url": "http://localhost:3027/mcp",
      "headers": {
        "API_KEY": "your-secret-key"
      }
    }
  }
}
```