git clone --recurse-submodules https://github.com/AaltoSciComp/scicomp-docs-assistant.git
cd scicomp-docs-assistant

git submodule update --init --recursive

cp .env.example .env
# Edit .env and set LLM_API_KEY=your-key-here

docker compose up --build

python3 -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt
cp .env.example .env   # set LLM_API_KEY

uvicorn app.main:app --reload --port 8080

LLM_API_KEY=your-provider-key
LLM_BASE_URL=https://your-provider.example.com/v1
LLM_MODEL=your-model-id

cp .env.mcp.example .env   # optional; compose works without .env for MCP-only
docker compose up --build

curl -s http://localhost:8081/api/health | python3 -m json.tool
# expect: "docs_present": true, "index_pages": 300+ (approx), "llm_configured": false

python3 -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt

uvicorn app.main:app --port 8080

source .venv/bin/activate   # after pip install -r requirements.txt
python -m app.mcp_stdio

{
  "mcpServers": {
    "scicomp-docs": {
      "command": "/path/to/scicomp-docs-assistant/.venv/bin/python",
      "args": ["-m", "app.mcp_stdio"],
      "cwd": "/path/to/scicomp-docs-assistant",
      "env": {
        "DOCS_ROOT": "/path/to/scicomp-docs-assistant/docs-source",
        "SKILLS_DIR": "/path/to/scicomp-docs-assistant/skills"
      }
    }
  }
}

{
  "mcpServers": {
    "scicomp-docs": {
      "url": "http://localhost:8081/mcp/"
    }
  }
}

{
  "mcpServers": {
    "scicomp-docs": {
      "command": "npx",
      "args": ["-y", "mcp-remote", "http://localhost:8081/mcp/"]
    }
  }
}

import asyncio
from mcp.client.session import ClientSession
from mcp.client.streamable_http import streamablehttp_client

async def main():
    async with streamablehttp_client("http://localhost:8081/mcp/") as (read, write, _):
        async with ClientSession(read, write) as session:
            await session.initialize()
            result = await session.call_tool("find_pages", {"query": "GPU sbatch"})
            print(result.content[0].text)

asyncio.run(main())

git submodule update --remote docs-source
docker compose up --build   # rebuild image so docs-source is refreshed

curl -s http://localhost:8081/api/health | python3 -m json.tool

app/
  main.py          # FastAPI + SSE chat + MCP mount
  mcp_server.py    # MCP tools, prompt, resource
  mcp_stdio.py     # stdio entry point (`python -m app.mcp_stdio`)
  agent.py         # Tool-calling loop
  doc_tools.py     # search / list / read (shared by agent + MCP)
  doc_index.py     # Page/heading index for find_pages
  config.py        # Settings from .env
  llm_client.py    # Gateway HTTP client
  static/          # Chat UI
skills/
  scicomp-docs-search.md
docs-source/       # scicomp-docs git submodule