MCP工具

1. Install dependencies

S18 uses uv and pyproject.toml as the canonical local setup:

uv sync

Docker

3. Run API + Ollama in Docker

Keep in .env:

S18_PROFILE=local-laptop-gemma
OLLAMA_BASE_URL=http://ollama:11434

Then:

docker compose --env-file .env.docker.ollama --profile ollama up --build -d

5. Verify (Docker mapping)

• API: http://localhost:8001
• Health: http://localhost:8001/health
• Docs: http://localhost:8001/docs
• Prometheus scrape: http://localhost:8001/metrics/prometheus

Persistent state is stored on host-mounted folders:

• data/
• memory/
• config/
• mcp_servers/faiss_index/

---

CI Docker target

This repo now includes a dedicated Docker build target for CI:

docker build --target ci -t s18share-ci .
docker run --rm s18share-ci

The CI target uses pinned dependencies from requirements-ci.txt (exported from uv.lock) and runs a quick compile sanity check.

---

GBrain bridge setup (optional)

GBrain runs Bun-first and can be wired as an MCP server (stdio). For the implemented mapping model and rollout plan, see docs/architecture/GBRAIN_COMPATIBILITY.md.

One-time local setup (from repo root):

git clone https://github.com/garrytan/gbrain.git gbrain
cd gbrain && bun install && bun run src/cli.ts init && cd ..

Verify MCP registration:

uv run python scripts/test_gbrain_mcp_registration.py
uv run python scripts/test_gbrain_mcp_live.py

---

Developer quickstart

Use this path if you want to run code and ship features quickly.

1. Follow Quick start (deps, env, run API).
2. Send a run request using Workflow-agnostic integrations.
3. Use Project structure to find where to change code.
4. Validate with tests in tests/ and scripts in scripts/.

Primary files:

• integrations/contracts.py
• integrations/adapters/*
• routers/runs.py
• config/settings_loader.py

Quick start: run with canonical metadata

POST /runs accepts optional integration metadata. If omitted, S18 falls back to the default adapter (integration_id=default, workflow_id=generic, contract_version=v1).

curl -X POST "http://localhost:8000/runs" \
  -H "Authorization: Bearer <supabase_access_token>" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "interpret CBC and suggest next steps",
    "integration_id": "wiseai",
    "workflow_id": "cdss",
    "contract_version": "v1",
    "source_system": "wiseai",
    "external_event_id": "evt_123",
    "consent_ref": "consent_abc",
    "raw_payload": {"hemoglobin": 12.1, "wbc": 7.5, "platelets": 220}
  }'

Agnostic example workflows

These examples are intentionally non-medical to demonstrate reusable core orchestration:

• examples/personal_finance/ - expense triage and budget actions
• examples/travel_planner/ - itinerary and logistics planning

Run either example by sending its run_payload.json to POST /runs.

Quick start

2. Environment variables

Optional:

• S18_PROFILE – Runtime profile overlay. Use local-laptop-gemma for Ollama mode or local-llama-cpp for llama.cpp mode.
• MCP_MODE – legacy (best-effort MCP startup) or strict (health/readiness requires listed MCP servers).
• MCP_REQUIRED_SERVERS – Comma-separated required MCP servers in strict mode (for example rag,sandbox for /runs with retrieval + sandbox tools).
• MCP_STARTUP_TIMEOUT_SECONDS – Startup budget for MCP server bring-up before readiness is evaluated.
• S18_CELERY_RUNS_QUEUE – Queue name for /runs background tasks (default celery).
• S18_CELERY_INGEST_QUEUE – Queue name for ingest pipeline tasks (default ingest).
• Ollama – Default local config points to http://127.0.0.1:11434. In Docker Compose, use OLLAMA_BASE_URL=http://ollama:11434 when using the bundled Ollama service.
• llama.cpp – Optional OpenAI-compatible server at LLAMA_CPP_BASE_URL. Use http://127.0.0.1:8080 for a host-local Python run, http://host.docker.internal:8080 when Docker API calls a host llama-server, or http://s18share-llama-cpp:8080 for the bundled Compose service.
• Git – Required for GitHub explorer features; the API will warn at startup if Git is not found.
• S18_HARNESS_STATE_DIR – Optional override for harness job storage location. If unset, harness state defaults to OS-local app data (for example %LOCALAPPDATA%/S18Share/harness_jobs on Windows).
• S18_CODEX_BIN / S18_CLAUDE_BIN / S18_GEMINI_BIN – Optional explicit binary paths for provider CLIs; otherwise harness resolves providers from PATH.
• EXTERNAL_MOCKEHR_BASE_URL – Preferred base URL of an upstream Mock EHR API. When set, the EHRDataMinerAgent's mockehr MCP fetches /patients/{id} and /patients/{id}/labs from that provider.
• WISE_MOCKEHR_BASE_URL – Backward-compatible alias for existing wise-ai environments; used when EXTERNAL_MOCKEHR_BASE_URL is not set.

1. Prepare environment file

cp .env.example .env

PowerShell:

Copy-Item .env.example .env

Set GEMINI_API_KEY in .env.

Configuration

• Main settings: config/settings.json (created from config/settings.defaults.json if missing).
• Override policy: keep stable defaults in config/settings.defaults.json, keep environment-specific values in config/settings.json, and prefer env vars for runtime overrides (AUTH_ENABLED, SUPABASE_*, TENANCY_*, RUN_POLL_TIMEOUT_SECONDS).
• Agent prompts and MCP: config/agent_config.yaml.
• REMME extraction prompt and options: under remme in settings.
• GBrain bridge flags: under remme.gbrain in config/settings.defaults.json:
• enabled, dual_write, read_from_bridge, mirror_dir, server_id

Harness jobs (trusted CLI runner)

The harness subsystem adds a BoringOS-style trusted runner to S18: the app can launch CLI jobs for codex, claude, and gemini, assuming those CLIs are already installed and authenticated on the host/deployed environment.

Endpoints

All routes are under /harness and are protected by Supabase-backed auth (require_supabase_user).

• POST /harness/jobs - create a new job and queue background execution
• GET /harness/jobs - list jobs (supports limit)
• GET /harness/jobs/{job_id} - fetch one persisted job state
• POST /harness/jobs/{job_id}/stop - request termination for a running job
• POST /harness/jobs/{job_id}/resume - publish a resume signal for a job
• GET /harness/jobs/{job_id}/events - stream job events over SSE (with optional history replay)

3. Run the API

uv run python api.py

Or:

uv run uvicorn api:app --host 0.0.0.0 --port 8000 --reload

• API: http://localhost:8000
• Health: http://localhost:8000/health
• Docs: http://localhost:8000/docs

The app expects a frontend at http://localhost:5173 (CORS is configured for it).

---

2. Run API only (host Ollama)

Set in .env:

S18_PROFILE=local-laptop-gemma
OLLAMA_BASE_URL=http://host.docker.internal:11434

Then:

docker compose --env-file .env.docker.ollama up --build -d api

4. Run API + host llama.cpp

For best llama.cpp performance, many users run llama-server directly on the host OS or a dedicated machine instead of inside Docker. Start an OpenAI-compatible llama.cpp server with embeddings enabled, for example:

llama-server -m ./models/model.gguf --host 0.0.0.0 --port 8080 --embeddings --pooling mean

If the S18 API runs in Docker and llama.cpp runs on the host, set:

S18_PROFILE=local-llama-cpp
LLAMA_CPP_BASE_URL=http://host.docker.internal:8080

Then:

docker compose --env-file .env.docker.llama-cpp-host up --build -d api

PowerShell shortcut:

.\scripts\use-llama-cpp.ps1 -HostServer

If you prefer the bundled Compose llama.cpp service instead, use:

.\scripts\use-llama-cpp.ps1

or run directly:

docker compose --env-file .env.docker.llama-cpp --profile llama_cpp up --build -d

Start API + Monitoring

docker compose up --build -d api
docker compose -f monitoring/docker-compose.monitoring.yml up -d

If you want local Ollama in Docker too:

docker compose up --build -d
docker compose -f monitoring/docker-compose.monitoring.yml up -d

Fresh architecture reference (latest)

• Canonical (Mar 2026 sync) - docs/architecture/WISE_AI_CDSS_Architecture_2026-03.md
• Previous conceptual baseline - docs/architecture/WISE_AI_CDSS_Architecture.md in wise-ai/TSAI-EAG-Capstone

Integration partner (wise-ai)

Use this path if you are integrating S18 with wise-ai workflows/endpoints.

1. Read Wise-AI Integration Sync (Mar 2026).
2. Set EXTERNAL_MOCKEHR_BASE_URL (or legacy WISE_MOCKEHR_BASE_URL) and verify endpoint reachability.
3. Send canonical POST /runs payloads with integration_id=wiseai, workflow_id=cdss.
4. Run the cross-stack verification commands in the Wise-AI section.

Primary files:

• integrations/adapters/wiseai.py
• config/integrations/wiseai_cdss_v1.json
• tests/integrations/

Workflow-agnostic integrations (Apr 2026)

S18Share is designed to decouple external product/workflow specifics from the orchestration core. Ingress requests are normalized into a canonical run contract, then routed through an integration adapter selected by integration_id (or source_system fallback).

• Canonical contract models: integrations/contracts.py
• Adapter interface + implementations: integrations/base.py, integrations/adapters/*
• Adapter registry + backward-compatible aliases: integrations/registry.py
• Productized core import surface: s18_engine/
• Config-driven integration profiles: config/integrations/*.json (example: wiseai_cdss_v1.json)
• Architecture deep-dive: docs/architecture/S18_WORKFLOW_AGNOSTIC_TARGET.md

Add a new integration (high level)

• Implement an adapter in integrations/adapters/<your_integration>.py (map raw → canonical, and canonical result → response envelope).
• Add a profile config/integrations/<integration>_<workflow>_<version>.json for risk/response profiles and field aliases.
• Add contract/registry/adapter tests under tests/integrations/.

MCP marketplace integration

S18 can operate as a central MCP hub for built-in and external servers.

• Integration guide: docs/mcp/MCP_MARKETPLACE_INTEGRATION.md
• Dynamic server controls: GET /mcp/servers, POST /mcp/servers, POST /mcp/refresh/{server}
• One-click server scaffold:

python scripts/scaffold_mcp_server.py --name weather

The scaffold creates a ready-to-run MCP server starter in mcp_servers/custom/.

Supabase integration contract (S18)

• Frontend/S18 performs login with Supabase Auth and sends Authorization: Bearer <access_token>.
• Backend verifies the JWT on protected endpoints using Supabase JWKS (/auth/v1/.well-known/jwks.json) with issuer/audience checks (no backend-managed Supabase session).
• If S18 is called through another backend/proxy, it also accepts X-Forwarded-Authorization: Bearer <access_token>.
• Optional persistence can write to two Supabase tables:
• ehr_request_log (inbound request/audit trail)
• ehr_clinical_result (normalized RAC/CBC/ABDM/FHIR-aligned outcome)
• Reference SQL schema: docs/supabase_ehr_schema.sql
• Quick environment/table readiness check:

python scripts/check_supabase_integration.py

Wise-AI Integration Sync (Mar 2026)

This section is a cross-repo integration reference. If you are onboarding to S18 itself, start with Start Here and Quick start.

Integration-focused technical changes completed

• MockEHR + Wise adapter path - Wise-side MockEHR adapter and S18-compatible tool stubs were integrated for cross-repo interoperability, with S18 consuming MockEHR data through MCP flows.
• CBC schema hardening - Added Pydantic clinical schema validation and follow-up fixes for CBC unit normalization and stable fast/full CDSS payload handling.
• MCP routing/tool-calling robustness - Improved MCP routing, timeout handling, retry/error behavior, and agent alias support for more reliable tool execution.
• Supabase integration touchpoints - Added/expanded Supabase-backed auth verification and optional request/result logging paths used by S18 integration flows.

When to use S18 vs orchestration frameworks

S18 is not trying to replace every graph or multi-agent library. It is a runtime layer around agentic systems: API contracts, model/provider configuration, memory/RAG, MCP servers, scheduled jobs, auth/logging hooks, and monitoring assets in one backend.

Use S18 when you need:

• A FastAPI surface for product integrations, especially a stable POST /runs contract.
• Runtime state, streaming, scheduler jobs, and operational visibility around agent workflows.
• A local-first path that can switch between laptop/private models and cloud providers.
• MCP tool orchestration as part of the backend instead of a one-off script.

Use LangGraph, CrewAI, AutoGen, or similar libraries directly when your main need is the agent-planning abstraction itself and you do not need S18's backend/runtime surface. S18 can coexist with those patterns by treating them as implementation choices behind adapters or agent-loop modules.