Smeldr MCP server
Commit Nov 14, 2026Maintains a searchable graph of decisions to ensure coherence between humans and AI agents through governance, ratification, and enforcement.
Also known as Smeldr/core
- Stars
- 10
- Tools
- —
- Downloads, 30 days
- —
- Latest version
- —
- Last commit
- Nov 14, 2026
- License
- AGPL-3.0
What is Smeldr MCP?
Smeldr maintains a searchable graph of decisions to ensure coherence between humans and AI agents through governance, ratification, and enforcement.
Summary generated from the project's README
About Smeldr MCP server
Software teams working with AI agents can use core to maintain a searchable graph of decisions that ensures coherence between humans and machines. It functions as a self-hosted governance system where people can ratify decisions and approve changes to specific file areas. By keeping decision reasoning separate from the context, it provides a clear record of who decided what and which rules are currently in force.
Users run the server locally or on their own infrastructure, and it includes a built-in SQLite database for storage. To connect an AI agent, you generate a specific agent token and provide it as a Bearer token to the MCP endpoint. The system distinguishes between human actors and agent actors, ensuring that while an agent can propose a decision or approve changes in an area, only a human can ratify a decision. This setup allows for enforcement through merge gates in pull requests, where a merge can wait for an approver to respond based on the decisions that apply to the modified files.
What you can do with it
- 1Propose and ratify decisionsAn AI agent can propose a new technical decision which a human then ratifies to make it official.
- 2Verify decision applicabilityA developer can ask which specific decisions apply to a particular file within a repository.
- 3Enforce governance via pull requestsTeams can set up merge gates that require an approver to respond before a pull request can be merged.
- 4Audit decision historyUsers can search the graph to see who made a decision and what the current standing of that rule is.
Written from the project's README. Every use case is checked against a quote from it.
Configuration
ENABLE_TOKENSSMELDR_BOOTSTRAP_TOKEN
Automated checks
Ran Nov 14, 2026Full report →Not verified yet. A server needs a score of 80, no serious finding, and enough data for us to check. How checks work · What to fix for more points
- Source repository linked and reachablesmeldr/core is public and reachablegithub.com/smeldr/core ↗Pass
- Package names this repository as its sourceNot checked
- Build provenance (Sigstore attestation)Not checked
- Open source license (OSI)AGPL-3.0spdx.org/licenses/AGPL-3.0.html ↗Pass
- Commit or release in the last yearLast commit or release 2026-11-13github.com/smeldr/core ↗Pass
- OpenSSF ScorecardNot checked
- Package name not close to a popular packageNot checked
- No critical advisory in the package or its dependenciesNot checked
- No hidden instructions to the model0 tool descriptions and the README read; no override phrases, credential paths or hidden charactersPass
- Destructive tools are labelledNot checked
- Remote endpoint answers the MCP handshakeNot checked
README
View on GitHubSmeldr
Keeps decisions coherent when people and AI agents move fast.
A searchable graph of your decisions: who decided, what is in force, and what builds on what. Kept apart from the context the reasoning came from.
Governance is set per domain and area: a domain's people ratify its decisions, an area's people approve changes to its files. Made for software teams that work with AI agents. Enforceable as merge gates when you want it.
Self-hosted. Open source. Nothing to install beside it: SQLite is built in (pure Go, modernc.org/sqlite).
- Decide. Propose a Decision. Someone with the right ratifies it. It is never edited, only replaced, and the old one stays on record.
- Know. Every action records who did it: a person, an AI agent or a job. Ask what is in force and what rests on it.
- Enforce. Tie a Decision to the files it governs. A pull request shows the Decisions that apply and waits for the answer.
v1.191.2: stable. Public APIs are stable within v1. See CHANGELOG.md.
Start in three minutes
1. Run the server.
Download the server for your system from the newest release and check it against the release's checksums.
In bash (Linux, macOS, Git Bash on Windows, WSL):
curl -LO https://github.com/Smeldr/core/releases/latest/download/smeldr-server-linux-amd64
curl -sL https://github.com/Smeldr/core/releases/latest/download/SHA256SUMS | grep smeldr-server-linux-amd64 | sha256sum -c
In PowerShell (Windows):
$u = 'https://github.com/Smeldr/core/releases/latest/download'
Invoke-WebRequest "$u/smeldr-server-windows-amd64.exe" -OutFile smeldr-server.exe
Invoke-WebRequest "$u/SHA256SUMS" -OutFile server-SHA256SUMS
(Get-FileHash smeldr-server.exe).Hash -eq (Select-String smeldr-server-windows-amd64.exe server-SHA256SUMS).Line.Split(' ')[0]
Only go on if the check prints smeldr-server-linux-amd64: OK (bash) or True (PowerShell). If it prints FAILED or False, delete the file and do not run it.
On another system, use the matching file from the release instead of linux-amd64:
- Linux on ARM:
linux-arm64. - macOS:
darwin-arm64(Apple silicon) ordarwin-amd64. Check withshasum -a 256 -c. A file downloaded in a browser is blocked by Gatekeeper until you runxattr -d com.apple.quarantine <file>. - Git Bash on Windows: the
windows-amd64.exefiles, renamed tosmeldr-server.exeandsmeldr-cli.exe. Git Bash still runs them as./smeldr-serverand./smeldr-cli. In WSL, use thelinux-amd64files as shown.
The .exe files are not code-signed. If you download one in a browser instead, Windows may warn about it. We have not tested that path, so use the download command above, and check the file either way. cmd.exe is not covered: use PowerShell or Git Bash.
Then start the server. In bash:
mv smeldr-server-linux-amd64 smeldr-server && chmod +x smeldr-server
SECRET=$(openssl rand -hex 32) BASE_URL=http://localhost:8080 \
ENABLE_TOKENS=1 ENABLE_GOVERNANCE=1 ENABLE_RELATIONS=1 ENABLE_GOVERNANCE_RECORDS=1 \
./smeldr-server
In PowerShell:
$b = New-Object byte[] 32; [Security.Cryptography.RandomNumberGenerator]::Create().GetBytes($b)
$env:SECRET = -join ($b | ForEach-Object { $_.ToString('x2') })
$env:BASE_URL = 'http://localhost:8080'
$env:ENABLE_TOKENS = '1'; $env:ENABLE_GOVERNANCE = '1'; $env:ENABLE_RELATIONS = '1'; $env:ENABLE_GOVERNANCE_RECORDS = '1'
.\smeldr-server.exe
latest/download always gives the newest release. For a fixed version, write download/vX.Y.Z instead, here and in step 2.
The server listens on 127.0.0.1:8080. If that port is taken, set PORT=8090 and BASE_URL=http://localhost:8090 (in PowerShell, $env:PORT and $env:BASE_URL), and use that URL in step 2. See docs/SELF_HOSTING.md for every setting.
We have run these steps end to end on Linux (2026-10-28) and on Windows 11 in PowerShell and in Git Bash (2026-10-31). Not yet on macOS.
You should see the bootstrap admin token, shown once, and then the ready line:
WARN smeldr: smeldr_tokens is empty: bootstrap admin token created (copy now, shown once):
<TOKEN>
smeldr-server: listening on 127.0.0.1:8080
The ready line appears only once the port is really bound. Leave it running.
2. Make a token for yourself, and one for your AI agent.
In a second terminal, in the same directory, download the CLI the same way and check it.
In bash:
curl -LO https://github.com/Smeldr/cli/releases/latest/download/smeldr-cli-linux-amd64
curl -sL https://github.com/Smeldr/cli/releases/latest/download/SHA256SUMS | grep smeldr-cli-linux-amd64 | sha256sum -c
In PowerShell:
$u = 'https://github.com/Smeldr/cli/releases/latest/download'
Invoke-WebRequest "$u/smeldr-cli-windows-amd64.exe" -OutFile smeldr-cli.exe
Invoke-WebRequest "$u/SHA256SUMS" -OutFile cli-SHA256SUMS
(Get-FileHash smeldr-cli.exe).Hash -eq (Select-String smeldr-cli-windows-amd64.exe cli-SHA256SUMS).Line.Split(' ')[0]
Only go on if the check prints smeldr-cli-linux-amd64: OK (bash) or True (PowerShell). If it prints FAILED or False, delete the file and do not run it.
Then run init with the bootstrap token from step 1. In bash:
mv smeldr-cli-linux-amd64 smeldr-cli && chmod +x smeldr-cli
SMELDR_BOOTSTRAP_TOKEN=<TOKEN> ./smeldr-cli init --url http://localhost:8080 --name <you>
In PowerShell:
$env:SMELDR_BOOTSTRAP_TOKEN = '<TOKEN>'
.\smeldr-cli.exe init --url http://localhost:8080 --name <you>
With Go 1.26.5 or later you can instead run go install smeldr.dev/cli/cmd/smeldr-cli@latest and drop the ./ below.
You should see:
OK connected to http://localhost:8080
OK token "<you>" created (class human, admin, 365 days)
OK grants: admin, approver (founder of the organization, D142): this token can ratify Decisions
OK .smeldr-cli.env written (mode 600; keep it out of version control: add it to .gitignore)
OK verification passed: the new token acts as admin
On Windows the fourth line reads:
OK .smeldr-cli.env written (on Windows the file is protected by your user profile's permissions, not by a file mode; keep it out of version control: add it to .gitignore)
The commands below are written as ./smeldr-cli; in PowerShell, write .\smeldr-cli.exe.
That token is yours, and it can ratify. Your AI agent gets its own, with less:
./smeldr-cli token create my-agent editor 30 --class agent --reason "my agent"
./smeldr-cli grant <token_id> editor --reason "my agent"
Point your agent at http://127.0.0.1:8080/mcp and give it that token as a Bearer token.
3. Ask it to propose a Decision.
Propose a Decision: "We never log session tokens."
You should see: a Decision in state proposed.
4. Try to ratify it as the agent.
A Decision has to be placed before it can be ratified. Ask for both in one go:
Place that Decision in the organization, then ratify it.
The agent places it (Decision D1 to the organization ORG1, belongs_to_organization), then tries to ratify and is refused:
{"code": -32001, "message": "forbidden: an agent token never ratifies, supersedes or amends a Decision (D142); a human approver does"}
That is the model at work: an AI agent proposes, a person decides. Now you ratify it:
./smeldr-cli transition Decision D1 --to ratified --reason "We never log session tokens"
D1 is now ratified, it holds, and it no longer awaits anyone.
5. Ask what applies to a file.
Which Decisions apply to
internal/billing/handler.goinacme/app?
The prompt must name a repository. On a fresh server the answer lists the path as uncovered, even for an organization-wide Decision, because no Area covers it:
{"repository":"acme/app","areas":[],"decisions":[],"uncovered":["internal/billing/handler.go"]}
After one Domain, one Area and one coverage rule (four calls):
{"repository":"acme/app","areas":[{"address":"ARE1","name":"Billing","approval_mode":"comment-only","domain":"DOM2","paths":["internal/billing/handler.go"],"rules":["COV1"]}],"decisions":[{"address":"D1","title":"We never log session tokens","state":"ratified","standing":"holds","place":"organization","place_address":"ORG1"}],"uncovered":[]}
That is the model. Next: gate your pull requests, with a GitHub App and a required status check.
What Smeldr gives you
Decisions that stay put
- Propose, ratify, replace. A ratified Decision is never edited; a new one supersedes it and both stay.
- Re-evaluate on a date, so nothing silently goes stale (needs
ENABLE_EVAL_QUEUE_DRAIN). - A Decision is in force (
holds), ceased or none, recorded on the item. Who started and who ended it is in the history (needsENABLE_PROVENANCE). - Two detectors flag an inconsistency: a Decision that contradicts another, and a Decision resting on one no longer in force. They flag, they do not prevent.
Places and roles
- Domains and Areas you name yourself. A domain's people ratify its Decisions; an area's people approve changes to its files.
- An AI agent can approve changes in one Area when a person has given it that right, for as long as the person says. A token classed as an agent never ratifies.
A record you can ask
- Search across every record you may read.
- Every write records who did it and what kind of actor it was: a person, an AI agent or a job (the bootstrap token and older tokens are unclassified). The full history and the reason, when one is given, need
ENABLE_PROVENANCE. - Every item says whether it awaits action.
Enforcement in code
- Ask which Decisions apply to a list of paths in a repository (needs an Area with a coverage rule).
- Pull request checks (
ENABLE_GITHUB, core v1.175.0 or later). In an Area set torequires-approval, with the check required in GitHub, a merge waits until the approver answers; the defaultcomment-onlydoes not wait. Smeldr does not read the code against the text of a Decision: the approver does.
The same model runs content
- Content types, publishing and scheduling, JSON, HTML and Markdown from one endpoint, sitemap, RSS, JSON-LD, AI indexing, and the same lifecycle and roles. See Use Smeldr as a Go library.
What a Decision looks like
A real Decision from this repo's own history (D59, excerpted for length):
{
"decision_number": "D59",
"state": "ratified",
"body": "Goals are places: new `contains` RelationStore kind (working name) gives Smeldr a first-class, user-defined taxonomy... Any item relates to a Goal via the new kind; the taxonomy is user/org-defined since Goals are already freely created, not a fixed enum.",
"next_eval_at": null
}
Smeldr's own architecture decisions are tracked as Decision items and ratified the same way any Smeldr-hosted decision is. Full text: DECISIONS.md.
More examples
example/server is a deployable binary with no hard-coded Go content types; define everything at runtime via MCP:
cd example/server
SECRET=$(openssl rand -hex 32) BASE_URL=http://localhost:8080 go run .
Optional subsystems are gated by environment variables (ENABLE_TOKENS,
ENABLE_GOVERNANCE, ENABLE_RELATIONS, ENABLE_DYNAMIC_CONTENT, ENABLE_BLOCKS,
ENABLE_MEDIA, ENABLE_SOCIAL, ENABLE_WEBHOOKS, ENABLE_PROVENANCE,
ENABLE_STRUCTURAL_SWEEP, ENABLE_AGENTS, ENABLE_GITHUB, OAUTH_ISSUER).
ENABLE_GITHUB turns on gated merges for a GitHub repository with environment
variables only (see docs/SELF_HOSTING.md).
Set any to a non-empty value to enable that subsystem. See example/server/main.go
for the full variable reference and wiring order.
Reference
Content types and the Go library: CONTENT.md
Full API reference: REFERENCE.md
Self-hosting (release binaries, config, backup/restore): SELF_HOSTING.md
Web docs: smeldr.dev/docs
For full token management reference (create, list, revoke) see REFERENCE.md: Token management.
For draft preview tokens see REFERENCE.md: Draft preview.
Dependencies
- The
smeldrpackage imports only the Go standard library. Its go.mod listsmodernc.org/sqliteand the modules it brings because the package's own tests use SQLite; a program that importssmeldr.dev/coredoes not compile them in. - The release binary
smeldr-serveris built without cgo from example/server, with SQLite compiled in (pure Go, modernc.org/sqlite) and the Smeldr modules. Nothing has to be installed beside it; the database is a file. - Postgres is optional: the separate module
smeldr.dev/core/pgx, with its own dependencies (pgx/go.mod). It is not in the release binary.
License
AGPL v3: free for individuals, open source projects, and companies building their own sites. A commercial license will be available for organisations running Smeldr as a hosted service. See COMMERCIAL.md.
Smeldr MCP questions
How do I start using Smeldr?
You can start by downloading the server binary for your system, verifying its checksum, and running it with the necessary environment variables.
Can AI agents ratify decisions in Smeldr?
No, AI agents can propose decisions, but only humans can ratify them. An agent token classed as an agent never ratifies, supersedes or amends a Decision.