# blawx-mcp
A minimal run-local MCP server (SSE over HTTP) that calls the Blawx API using a Blawx API key.
## Prereqs
- Python 3.10+
## Install
From this repo root:
```bash
python -m pip install -e .
```
## Configuration
Set required configuration in your environment:
```bash
export BLAWX_API_KEY="your_key_here"
export BLAWX_TEAM_SLUG="your_team_slug"
export BLAWX_PROJECT_ID="42"
```
You will find the Blawx Project ID and team slug in the URL of your
web browser when you go to the home page for your project. The
pattern will be
`https://app.blawx.dev/a/{team_slug}/project/{project_id}`
You can create a Blawx API Key if you have a Pro subscription to Blawx.
Click on "Profile" in the left navigation bar, and find the "Add API
Key" button. When you click the button your API key will be displayed
only once at the top of the screen. Copy and paste it into your
environment settings.
## Run
Run the MCP server from this folder (no install required):
```bash
./.venv/bin/python -m blawx_mcp
```
Defaults:
- Binds to `127.0.0.1:8765`
- SSE endpoint at `http://127.0.0.1:8765/sse`
Optional server bind overrides:
```bash
export BLAWX_MCP_HOST="127.0.0.1"
export BLAWX_MCP_PORT="8765"
```
## Connect to Your Coding Agent
Coding agents differ in how they configure MCP servers. This is a typical
tool definition in your `mcp.json` for VS Code.
```
{
"servers": {
"my-blawx-sse-server": {
"url": "http://127.0.0.1:8765/sse",
"type": "http"
}
},
"inputs": []
}
```
## Tools
These tools give your coding agent the following capabilities:
1. Discover what the project exposes (questions, fact scenarios, ontology).
2. Ask a question (using either a stored fact scenario or a custom facts payload).
3. Browse answers and drill into explanations (model/attributes/explanation text).
Here's a brief run-down of the available tools.
### Health check
- `blawx_health`: verifies the Blawx app is reachable and returns status/body.
### Discover Project Content
Agents will usually start by listing the available questions,
fact scenarios, and vocabulary.
- `blawx_questions_list`: lists shared questions available in the project.
- `blawx_question_detail`: retrieves a specific question's details (useful when deciding which question id to ask).
- `blawx_fact_scenarios_list`: lists stored fact scenarios (prebuilt sets of facts you can re-use).
- `blawx_fact_scenario_detail`: shows the facts contained in a specific fact scenario.
- `blawx_ontology_list`: lists ontology categories/relationships (the project's vocabulary).
- `blawx_ontology_category_detail`: details for a specific category.
- `blawx_ontology_relationship_detail`: details for a specific relationship (including arity/parameters).
### Ask Questions
- `blawx_question_ask_with_fact_scenario`: asks a question using a stored fact scenario.
- `blawx_question_ask_with_facts`: asks a question using an explicit facts payload generated by your agent based on your
instructions.
**NB**: It's not clear how good agents will be at generating
representations of complicated fact scenarios in complicated
vocabularies. It can be helpful to review how your agent
formulated your fact scenario if you get unexpected results,
and to give it hints on how to do better.
When you pose a question, the answer is saved on the Blawx
server for approximately 30 minutes, and your agent can
review it over that period of time. Once the data expires,
your agent will need to pose the qestion again to analyse
the responses further. Based on the instructions provided
by the MCP server, it should know to do that when and if
required.
### Review Answers
Blawx's answers can be quite large, and agents have a limited
context window, so the process of reviewing
answers is broken into multiple steps.
1. Get the list of answers to the question.
2. Get the list of explanations for a specific answer.
3. Look at the parts of a specific explanation.
- `blawx_list_answers`: gives the list of answers available,
and the bindings in those answers.
- `blawx_list_explanations`: gives the list of explanations available for an answer
There are four tools to retrieve specific parts of an
explanation. These tools all allow the agent to select the
entire part, or if it is too long, to select only certain
lines at a time.
- `blawx_get_model_part`: this returns the answer set
- `blawx_get_attributes_part`: this returns the constraints applied to variables in the model and explanations
- `blawx_get_explanation_part`: this is the tree-structured,
human-readable explanation for the answer
- `blawx_get_constraint_satisfaction_part`: this is the portion
of the explanation that shows how global constraints were satisfied. This is often both verbose and unhelpful, so it
is separated out. You may need to ask your agent to seek it
specifically if you know your encoding uses constraints and
you need to know how they are satisfied.
**NB**: The other three parts should be read alongisde the
attributes, or relevant information may be missing. This
instruction is provided to the agent, but if it isn't followed
your agent may draw incorrect conclusions. It may be wise to
instruct your agent to check the attributes in addition to
the other parts of an explanation.
## Development
The Blawx server used can be overridden for local development
- `BLAWX_BASE_URL` (default: `https://app.blawx.dev`)
