# AI App MCP

A production-ready Python MCP server that supports both stdio and Streamable HTTP transports.

## Features

- `health_check`: return server health and runtime configuration.
- `normalize_user_query`: normalize user text before retrieval or agent routing.
- `search_knowledge_base`: search local `.md`, `.txt`, and `.json` files.
- `get_document`: read a safe document from the configured knowledge directory.
- `build_rag_prompt`: build a grounded RAG prompt.
- `config://runtime`: expose safe runtime configuration.
- `rag_answer_prompt`: reusable RAG prompt template.

## Install

```powershell
cd D:\projects\codex\single\mcp
python -m venv .venv
.\.venv\Scripts\Activate.ps1
pip install -e ".[dev]"
Copy-Item .env.example .env
```

## Transport 1: stdio

Use stdio when an AI client starts this MCP server as a local child process.

```powershell
ai-app-mcp --transport stdio
```

Equivalent module command:

```powershell
python -m ai_app_mcp.server --transport stdio
```

Client configuration example:

```json
{
  "mcpServers": {
    "ai-app-mcp": {
      "command": "python",
      "args": [
        "-m",
        "ai_app_mcp.server",
        "--transport",
        "stdio"
      ],
      "env": {
        "MCP_KNOWLEDGE_DIR": "D:/projects/codex/single/mcp/knowledge"
      }
    }
  }
}
```

In stdio mode, stdout is used for MCP protocol messages. Logs are written to stderr.

## Transport 2: Streamable HTTP

Use Streamable HTTP for MCP Inspector, HTTP debugging, or service-to-service integration.

```powershell
ai-app-mcp --transport streamable-http --host 127.0.0.1 --port 8000
```

Equivalent module command:

```powershell
python -m ai_app_mcp.server --transport streamable-http --host 127.0.0.1 --port 8000
```

MCP endpoint:

```text
http://127.0.0.1:8000/mcp
```

Do not open this endpoint directly as a normal web page. It is a JSON-RPC MCP endpoint and requires an MCP client.

## Debug With MCP Inspector

Start this MCP server:

```powershell
ai-app-mcp --transport streamable-http --host 127.0.0.1 --port 8000
```

Start Inspector:

```powershell
npx -y @modelcontextprotocol/inspector
```

Open:

```text
http://localhost:6274
```

Use:

```text
Transport: Streamable HTTP
URL: http://127.0.0.1:8000/mcp
```

## Environment

Copy `.env.example` to `.env` and adjust values:

```env
MCP_SERVER_NAME=ai-app-mcp
MCP_LOG_LEVEL=INFO
MCP_KNOWLEDGE_DIR=./knowledge
MCP_MAX_TEXT_CHARS=12000
```

## Knowledge Directory

By default, the server reads files from `./knowledge`. Only `.md`, `.txt`, and `.json` files are allowed. Paths are resolved safely so clients cannot read files outside the knowledge directory.

## Test

```powershell
pytest
```