Metadata-Version: 2.4
Name: wquestions-mcp
Version: 0.2.0
Summary: Model any domain in 7 questions — a WQuestions MCP server.
Author: Jose Abanto Marin
License: MIT License
        
        Copyright (c) 2026 Jose Abanto Marin
        
        Permission is hereby granted, free of charge, to any person obtaining a copy
        of this software and associated documentation files (the "Software"), to deal
        in the Software without restriction, including without limitation the rights
        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
        copies of the Software, and to permit persons to whom the Software is
        furnished to do so, subject to the following conditions:
        
        The above copyright notice and this permission notice shall be included in all
        copies or substantial portions of the Software.
        
        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
        SOFTWARE.
        
Project-URL: Homepage, https://github.com/joseabantomarin/wquestions-mcp
Project-URL: Repository, https://github.com/joseabantomarin/wquestions-mcp
Keywords: mcp,llm,knowledge-graph,ontology,wquestions,ai
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Intended Audience :: Developers
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: mcp>=1.2
Dynamic: license-file

# wquestions-mcp

**Model any domain in 7 questions.**

An MCP server that lets Claude Desktop (or any MCP client) build and query a
knowledge model of *anything* — a spa, a barbershop, a clinic, a bank — using
one fixed set of tools. No per-domain schema to write, ever.

## The problem

Every domain today gets its own bespoke ontology or database schema: a CRM
schema for sales, a clinical model for a clinic, a different one again for a
bank or a taxi dispatcher. None of it transfers between domains, and none of
it was designed for an LLM to reason over — each new domain means new
modeling work before an AI can even start answering questions about it.

WQuestions replaces all of that with a single fixed index: **7 axes** that
any fact, in any domain, answers. Model a domain by asserting facts on those
7 axes; query it the same way no matter what the domain is.

## The 7 axes

| Axis | Question | Holds |
|---|---|---|
| Q | who | agents |
| O | what | objects, and reified situations (facts treated as things) |
| L | where | places |
| T | when | time points and intervals |
| N | how much | magnitudes with a unit |
| K | which / what kind | atemporal categories, types, states |
| M | how | the predicates that connect Q/O/L/T/N/K to each other — structural, not a value axis |

![demo](https://raw.githubusercontent.com/joseabantomarin/wquestions-mcp/main/docs/demo.gif)

## Quickstart

Add this to your Claude Desktop config (`claude_desktop_config.json`) and
restart Claude Desktop:

```json
{
  "mcpServers": {
    "wquestions": {
      "command": "uvx",
      "args": ["wquestions-mcp"]
    }
  }
}
```

Prefer to run from source? Clone this repo and, from the repo root,
`pip install -e .` into a virtualenv (the engine is bundled — no other
package needed). Then point `command`/`args` at that venv's `wquestions-mcp`
script (e.g. `command: ".../.venv/bin/wquestions-mcp"`, `args: []`) instead
of `uvx`.

Then ask Claude: *"Load the spa example, then show me the model."* See
[`DEMO.md`](DEMO.md) for the full 30-second walkthrough.

## Tools

| Tool | Does |
|---|---|
| `list_axes` | Describe the 7 axes |
| `list_roles` | List canonical roles (who/what/where/... connectors), typed by domain and range |
| `add_entity` | Create an individual on a value axis (Q, O, L, T, N, K); for the N axis pass `value` + `unit` (a K entity id or inline spec) — a magnitude without a unit is rejected |
| `define_verb` | Register a situation type and its roles — optional, `assert_situation` auto-registers unknown verbs |
| `assert_situation` | Assert a fact: reify a situation and attach its roles |
| `correct` | Correct/update a role on an existing situation by re-asserting it (append-only; `ask` returns the latest, `history=true` shows the trail) |
| `ask` | Query by projection — fix some roles, ask for others, optionally as of a point in time; pass `history=true` for the full time-ordered trail instead of just the current value |
| `show_model` | Dump the current universe: every entity and fact |
| `load_example` | Load a prebuilt demo universe (`spa`) to try queries instantly |
| `reset` | Clear the model and start a fresh universe |

## How it works

The LLM client does the natural-language-to-structure step: it reads "Diego
cut Marco's hair at Barber Kings on 2025-06-11" and turns it into
role-labeled arguments (`agente: diego, paciente: marco, lugar_de:
barber_kings`). The server never parses English — it takes those roles,
validates them against the 7-axis model, and runs ingest and query over the
`wq` engine. Same engine, same 10 tools, whether the domain behind them is a
spa or a barbershop.

## Persistence

By default the server persists your universe to an append-only log and reloads
on restart, so a modeled domain survives across sessions — you never rebuild by
hand. Nothing is ever overwritten; corrections are appended and the log is the
source of truth.

- **Default location:** `~/.wquestions/universe.jsonl`.
- **Choose a file:** set `WQUESTIONS_LOG=/path/to/domain.jsonl`. Point each domain
  at its own file (e.g. one per MCP server entry in your client config) — a single
  log holds one live universe at a time (a `reset` starts a fresh domain within it).
- **Turn it off (pure in-memory):** `WQUESTIONS_LOG=off`.

`show_model` reports the active log path and how many events were replayed, so
you can confirm persistence is on.

## Further reading

The 7-axis model — why it's fixed, what each axis actually commits to, and
how it holds up once you push on it — is worked out in full in *WQuestions*,
the book this project comes from (Spanish). Start with
[Chapter 8, El espacio multidimensional](https://joseabantomarin.github.io/WQuestions/08-espacio-multidimensional.html)
for the axis model itself, or the
[table of contents](https://joseabantomarin.github.io/WQuestions/00-introduccion.html).
