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

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.

ai-app-mcp --transport stdio

Equivalent module command:

python -m ai_app_mcp.server --transport stdio

Client configuration example:

{
  "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.

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

Equivalent module command:

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

MCP endpoint:

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:

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

Start Inspector:

npx -y @modelcontextprotocol/inspector

Open:

http://localhost:6274

Use:

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

Environment

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

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

pytest