모든 수치 데이터를 특정 데이터베이스 소스 행까지 추적하여 금융 및 ERP 데이터의 AI 환각 현상을 방지합니다.
다른 이름 brick-byte/footnote, @brick-byte/footnote
- 스타
- 0
- Tools
- —
- 다운로드, 30일
- 819
- 최신 버전
- 0.2.0
- 마지막 커밋
- 2026년 11월 4일
- 라이선스
- MIT
footnote MCP란?
footnote은(는) MCP server입니다. 모든 수치 데이터를 특정 데이터베이스 소스 행까지 추적하여 금융 및 ERP 데이터의 AI 환각 현상을 방지합니다.
프로젝트 README에서 생성된 요약
footnote MCP server 정보
금융 분석가와 ERP 데이터를 다루는 개발자는 footnote를 사용하여 모든 수치 데이터가 특정 데이터베이스 행까지 추적되도록 함으로써 AI 환각 현상을 방지할 수 있습니다. 언어 모델이 숫자를 생성하도록 허용하는 대신, 이 서버는 결정론적 코어를 사용하여 모델이 유형화된 작업 카탈로그에서 선택하도록 하고 SQL이 모든 집계 작업을 처리합니다. 이를 통해 모델이 숫자를 지어내는 것이 아니라 시스템 기록에서 값을 그대로 복사하도록 보장합니다.
이 서버는 MCP server이자 출처 저장소로 작동하며, ERP 데이터베이스에 대한 읽기 전용 연결과 감사 추적을 위한 별도의 추가 전용 데이터베이스가 필요합니다. Claude Desktop, Cursor, LangChain과 같은 클라이언트와 호환됩니다. 데이터 무결성을 유지하기 위해 서버는 서버 측에서 작성되는 조작 방지 해시 체인 방식의 출처 로그를 강제하며, 이는 모델이 감사 추적에 영향을 미칠 수 없음을 의미합니다. 이러한 구성은 클릭 가능한 인용과 내보낼 수 있는 증거를 감사인에게 제공하므로, 높은 신뢰도가 요구되는 조달 또는 재고 관리 환경에 적합합니다.
활용 사례
- 1금융 주장 검증감사인은 AI 응답에 포함된 금액을 클릭하여 해당 합계를 생성한 정확한 송장 기록을 확인할 수 있습니다.
- 2허위 고객 데이터 방지모델이 존재하지 않는 고객을 조회하려고 시도하면, 서버는 모델이 이야기를 지어내도록 두는 대신 실제 대안과 함께 복구 가능한 오류를 반환합니다.
- 3AI 추론 감사AI가 위험에 대한 판단을 제공할 때, 서버는 결론을 별도로 인용되고 검증 가능한 사실들로 분해합니다.
- 4데이터 무결성 보장개발자는 검증 명령을 실행하여 과거의 감사 로그가 수정되지 않았는지 확인할 수 있습니다.
프로젝트의 README를 바탕으로 작성되었습니다. 모든 활용 사례는 해당 내용의 인용문과 대조하여 확인합니다.
footnote MCP 설치 방법
형식 확인: 2026년 11월 10일Cursor에 추가Goose에 추가Claude Code에 footnote MCP 설치
$ claude mcp add --env 'DATABASE_URL=<YOUR_DATABASE_URL>' footnote -- npx -y @brick-byte/footnoteCursor에 footnote MCP 설치
~/.cursor/mcp.json
{
"mcpServers": {
"footnote": {
"command": "npx",
"args": [
"-y",
"@brick-byte/footnote"
],
"env": {
"DATABASE_URL": "<YOUR_DATABASE_URL>"
}
}
}
}VS Code에 footnote MCP 설치
.vscode/mcp.json
{
"servers": {
"footnote": {
"type": "stdio",
"command": "npx",
"args": [
"-y",
"@brick-byte/footnote"
],
"env": {
"DATABASE_URL": "<YOUR_DATABASE_URL>"
}
}
}
}VS Code CLI에 footnote MCP 설치
$ code --add-mcp '{"name":"footnote","type":"stdio","command":"npx","args":["-y","@brick-byte/footnote"],"env":{"DATABASE_URL":"<YOUR_DATABASE_URL>"}}'Claude Desktop에 footnote MCP 설치
claude_desktop_config.json
{
"mcpServers": {
"footnote": {
"command": "npx",
"args": [
"-y",
"@brick-byte/footnote"
],
"env": {
"DATABASE_URL": "<YOUR_DATABASE_URL>"
}
}
}
}Codex에 footnote MCP 설치
$ codex mcp add footnote --env 'DATABASE_URL=<YOUR_DATABASE_URL>' -- npx -y @brick-byte/footnoteCodex config.toml에 footnote MCP 설치
~/.codex/config.toml
[mcp_servers.footnote] command = "npx" args = ["-y", "@brick-byte/footnote"] [mcp_servers.footnote.env] DATABASE_URL = "<YOUR_DATABASE_URL>"
Gemini CLI에 footnote MCP 설치
$ gemini mcp add -s user -e 'DATABASE_URL=<YOUR_DATABASE_URL>' footnote npx -- -y @brick-byte/footnoteGemini settings.json에 footnote MCP 설치
~/.gemini/settings.json
{
"mcpServers": {
"footnote": {
"command": "npx",
"args": [
"-y",
"@brick-byte/footnote"
],
"env": {
"DATABASE_URL": "<YOUR_DATABASE_URL>"
}
}
}
}구성
DATABASE_URL비밀Postgres connection string. Omit to use the built-in SQLite sample database.
PROVENANCE_ACTORIdentity recorded against each provenance record. In production this comes from the request's auth.
PROVENANCE_DBPath to the SQLite provenance log. Defaults to in-memory, which discards the trail on exit.
| 이름 | 설명 | 유형 |
|---|---|---|
| DATABASE_URL | Postgres connection string. Omit to use the built-in SQLite sample database. | 비밀 |
| PROVENANCE_ACTOR | Identity recorded against each provenance record. In production this comes from the request's auth. | |
| PROVENANCE_DB | Path to the SQLite provenance log. Defaults to in-memory, which discards the trail on exit. |
자동 검사
2026년 11월 14일에 실행됨전체 보고서 →자동 검사를 통과했습니다. 이는 보안 감사가 아닙니다. 코드를 직접 읽고 서버에 필요한 최소한의 권한만 부여하십시오. 검사 방식
- 소스 저장소 연결 및 접근 가능brick-byte/footnote is public and reachablegithub.com/brick-byte/footnote ↗통과
- 패키지가 이 저장소를 소스로 명시@brick-byte/footnote names brick-byte/footnote as sourcenpmjs.com/package/@brick-byte/footnote ↗통과
- 빌드 출처(Sigstore 증명)No build attestation published for this release검사되지 않음
- 오픈 소스 라이선스 (OSI)MITspdx.org/licenses/MIT.html ↗통과
- 최근 1년 내 커밋 또는 릴리스Last commit or release 2026-11-05github.com/brick-byte/footnote ↗통과
- OpenSSF Scorecard검사되지 않음
- 패키지 이름이 인기 패키지와 유사하지 않음No popular package one edit away from @brick-byte/footnote통과
- 패키지 및 해당 종속성에 중요한 보안 권고 없음113 resolved dependencies checked; no critical advisoryosv.dev ↗통과
- 모델에 대한 숨겨진 지침 없음0 tool descriptions and the README read; no override phrases, credential paths or hidden characters통과
- 파괴적인 도구에 라벨 표시됨검사되지 않음
- 원격 엔드포인트가 MCP 핸드셰이크에 응답검사되지 않음
README
GitHub에서 보기Footnote
An MCP server that prevents hallucinated numbers when AI answers questions over ERP and finance data. Every figure in an answer traces back to the database rows that produced it: clickable at read time, exportable for an auditor, and tamper-evident.
Works with any MCP client: Claude Desktop, Cursor, Microsoft Agent Framework, Semantic Kernel (.NET), LangChain, or your own loop.
An MCP server, a provenance store, and a demo UI showing what the combination looks like.
The quickest way to try it:
// claude_desktop_config.json — sample data, nothing to install
{ "mcpServers": {
"footnote": {
"command": "npx",
"args": ["-y", "@brick-byte/footnote"],
"env": { "PROVENANCE_ACTOR": "your-name" }
} } }
Against your own database it reads from two, never one — the ERP read-only, the audit trail somewhere you own. Run footnote check first; see Connecting to an existing database.
{ "mcpServers": {
"footnote": {
"command": "npx",
"args": ["-y", "@brick-byte/footnote"],
"env": {
// Read-only role. Footnote never writes here and never migrates it.
"DATABASE_URL": "postgres://footnote_ro:pass@host:5432/erp",
// The append-only provenance log, deliberately a separate database.
"PROVENANCE_DB": "/path/to/footnote-provenance.db",
"PROVENANCE_ACTOR": "your-name"
}
} } }
Or run the demo UI locally:
npm install
npm run demo # http://localhost:4711
npm test # 30 tests, including the invariants below
Node 22.5+ required (uses the built-in node:sqlite, so there is no database to install).
Postgres is opt-in. The same schema, seed and query set run against it, and the same suite has to pass on both:
npm run db:up # Postgres 17 in Docker, seeded from migrations/001_init.sql
npm run test:pg # the same suite + 2 Postgres-only checks (32)
npm run demo:pg # the demo, against Postgres

The problem
Language models produce plausible continuations, not true ones. Point one at a business database and it will confidently report a number that no query produced — and the fabricated figure is indistinguishable from the real one, because both come out of the same machinery.
The usual answers don't hold up here. Uncertainty signals catch the fuzzy cases, not the fluent ones. A verifier built from the same model can confirm a fabrication as easily as catch it. And in finance, inventory or procurement, "the model said so" is not an answer anyone can act on.
What does work is structural: never let the model produce the number.
The architecture
question
│
▼
model ──────────► picks an operation from a catalog and supplies typed args
│ (it cannot write SQL, cannot invent an operation)
▼
contract layer ─► validates params, resolves entities against the database,
│ rejects anything that does not exist
▼
deterministic ──► executes the query; SQL does all aggregation
core returns values + the evidence behind each one
│
▼
provenance ─────► appends a hash-chained record, server-side,
store where the model cannot influence it
│
▼
host UI ────────► fills slots from structured output and renders each
claim as a clickable citation
The model handles translation and phrasing — the two things it is reliable at. Numbers come from the system of record.
What it enforces
These are tests, not guidelines. npm test fails if any of them breaks.
No number is generated. Values are copied verbatim from an operation's structured output into template slots. A test asserts every monetary figure in an answer is covered by a claim with evidence behind it, and that the stated total equals the sum of the records it cites.
Entities are validated before any query runs. A fabricated customer produces a recoverable error listing real alternatives — not a silent empty result the model narrates around.
Aggregation happens in SQL. The model chooses which aggregation to run, never what it equals.
Empty results are handled in code. This is the single biggest fabrication trigger: hand a model an empty result set mid-sentence and it invents something to finish the sentence. Operations set an explicit emptyReason instead.
Unroutable questions are refused. "What will revenue be next quarter?" maps to no operation, so no answer is produced. Refusal is a first-class outcome, not a failure.
Provenance is written server-side. The model never reports its own provenance. Provenance that depends on the model choosing to cite is worthless.
The log is tamper-evident. Each record carries the hash of its predecessor. npm run verify walks the chain and reports the first record that was modified after it was written.
Query ordering is a tested contract. listCustomers must return record order, because entity extraction takes the first match. Sorting it by name instead produces the failure this project exists to prevent: a fluent sentence, a real figure, correctly cited to real rows, about the wrong company. There is a test for exactly that.
Interpretations, not just figures
The harder case is judgement. "Bergmann is at risk" is a conclusion with no row to check it against — and an ungrounded interpretation is more dangerous than an ungrounded number, because it reads as insight and survives review.
The answer here states the conclusion and then lays out each premise as a separately cited fact:
Bergmann Logistik GmbH shows two independent risk signals.
This is an interpretation — the underlying facts are:
· 43.805,00 € overdue across 4 invoices, oldest 104 days past due
· 2 open support tickets, 1 high severity
· agreed payment terms of 30 days, account owned by Ana Kovač
The conclusion is the model's. Every fact above is a record you can open.
A human can disagree with the reasoning while trusting the inputs.
Provenance record format
{
"id": "…", "sequence": 1, "timestamp": "2026-08-14T09:12:04.000Z",
"actor": { "id": "zoran", "role": "controller" },
"question": "How much does Bergmann owe?",
"answer": "Bergmann Logistik GmbH is 43.805,00 € overdue across 4 invoices…",
// Each claim indexes a span of the answer and names its evidence.
"claims": [
{
"text": "43.805,00 €",
"span": { "start": 25, "end": 36 },
"evidenceIds": ["invoice:8812", "invoice:8834", "invoice:8901", "invoice:8977"],
"origin": "structured" // never "generated" for a value
}
],
// The query, so the result is reproducible.
"operations": [
{ "name": "getOverdueInvoices",
"arguments": { "customer": "Bergmann", "asOfDate": "2026-08-14" },
"query": { "sql": "SELECT …", "params": ["2026-08-14", 4471, "2026-08-14"] },
"durationMs": 0.42 }
],
// Field values, not just IDs — the export stands alone if the source moves on.
"evidence": [
{ "id": "invoice:8812", "type": "invoice", "recordId": "8812",
"uri": "erp://invoice/8812",
"fields": { "number": "INV-2026-8812", "due_on": "2026-05-02",
"outstanding": "18.450,00 €", "days_overdue": 104 } }
],
"previousHash": "0000…", "hash": "9aa2ba…"
}
origin is the field that matters. structured means the value was copied from an operation's output. generated means a model produced it — which for a number is exactly what this project exists to prevent.
MCP details
The server uses the parts of the protocol that carry this work:
| Feature | Use |
|---|---|
inputSchema |
The model gets a typed catalog, not a query language |
structuredContent |
Values return as validated JSON beside the prose, so figures never have to survive a round trip through generated tokens |
resource_link |
Every record touched comes back as an erp:// URI — the deep-link primitive behind a clickable citation |
annotations.audience |
Record links are marked user-facing |
_meta |
Carries the provenance record ID and hash so a host can fetch the full trace |
isError |
A fabricated entity is a recoverable tool error the model can correct, not a protocol failure |
What MCP does not give you, and what this repo adds: nothing in the protocol binds this claim to that evidence. The protocol hands you links; the claim-to-evidence mapping and its rendering live in the host. That binding is the actual product.
Run standalone over stdio:
npm run mcp
The claude_desktop_config.json entry is at the top of this README.
Running from source (for development)
{ "mcpServers": {
"footnote": {
"command": "npx",
"args": ["tsx", "--experimental-sqlite", "/path/to/footnote/src/mcp-server.ts"],
"env": { "PROVENANCE_DB": "/path/to/provenance.db", "PROVENANCE_ACTOR": "your-name" }
} } }
Connecting to an existing database
By default Footnote runs against its own throwaway sample database. Set DATABASE_URL and it switches to external mode, meant for a database it did not create — a customer's ERP.
External mode changes three things, all of them about not damaging a system that isn't ours:
- The migration never runs. In demo mode Footnote creates and seeds
customers,invoices,paymentsandtickets. Against a real database that would either crash on a read-only role or, worse, succeed — inserting fabricated invoices into a live finance system.FOOTNOTE_SEED=1is the only way to opt back in, and exists for our own Docker Postgres. - The ERP connection is read-only at the session level. Every pool connection starts with
default_transaction_read_only=onand astatement_timeout. The catalog only ever emitsSELECT, but that is a property of code someone can change; this is enforced by the server. - The provenance log goes somewhere else. It is append-only and needs write access, so it never shares the ERP connection. Writing an audit trail into the database being audited would mean asking for write access to the very system under audit.
Create a read-only role
CREATE ROLE footnote_ro LOGIN PASSWORD '…';
GRANT CONNECT ON DATABASE your_erp TO footnote_ro;
GRANT USAGE ON SCHEMA public TO footnote_ro;
GRANT SELECT ON ALL TABLES IN SCHEMA public TO footnote_ro;
-- Postgres 15+ already revokes this from PUBLIC; older versions do not.
REVOKE CREATE ON SCHEMA public FROM footnote_ro, PUBLIC;
-- So tables added later are readable too, without re-granting by hand.
ALTER DEFAULT PRIVILEGES IN SCHEMA public GRANT SELECT ON TABLES TO footnote_ro;
Environment variables
| Variable | Default | Purpose |
|---|---|---|
DATABASE_URL |
unset | The ERP. Setting it enables external mode. Unset means demo mode. |
PROVENANCE_DATABASE_URL |
unset | Postgres for the provenance log. Never falls back to DATABASE_URL. |
PROVENANCE_DB |
./footnote-provenance.db in external mode, :memory: in demo |
SQLite path for the provenance log, when PROVENANCE_DATABASE_URL is unset. |
FOOTNOTE_SEED |
unset | 1 applies the demo schema and seed. Never set this against a customer database. It also makes the ERP connection writable, because seeding writes. |
FOOTNOTE_STATEMENT_TIMEOUT_MS |
5000 |
Statement timeout on the ERP connection. |
PROVENANCE_ACTOR / PROVENANCE_ROLE |
mcp-client / unknown |
Identity recorded against each provenance record. |
Check before you connect
DATABASE_URL=postgres://footnote_ro:…@host:5432/erp npm run check
or, from the installed package, footnote check. It reports the server version, whether those credentials can write, what they can read, which catalog tables and columns are missing, and whether the provenance store opens with an intact chain. It exits non-zero on a finding, so it works as a deployment gate.
The write probe deliberately connects without the read-only session flag — probing through our own default_transaction_read_only=on would have the server reject the write every time and report a pass against a role with full write access. It creates a table inside a transaction that is always rolled back, then verifies nothing was left behind.
Expose your data as views
The catalog reads fixed table and column names and never guesses at mappings. If your schema differs — and it will — create views rather than renaming anything:
CREATE VIEW invoices AS
SELECT ar_doc_id AS id,
doc_number AS number,
bp_id AS customer_id,
doc_date::text AS issued_on,
net_due_date::text AS due_on,
curr AS currency,
ROUND(gross_amt * 100)::bigint AS amount_cents,
ROUND(paid_amt * 100)::bigint AS paid_cents,
CASE WHEN clearing_date IS NOT NULL THEN 'paid' ELSE 'open' END AS status
FROM fi_open_items;
Two things that will bite otherwise: dates must come back as text in YYYY-MM-DD, because a driver-returned Date object renders as Tue May 02 2026 … inside claim text and breaks the span offsets that make citations clickable; and money must be integer cents, never floats. npm run check lists exactly which columns are missing.
What you get over plain MCP, and what needs host integration
Any MCP client — Claude Desktop, Microsoft Agent Framework, Semantic Kernel, LangChain, your own loop — can call this server today. What that gives you:
- a fixed catalog of typed operations; the model cannot write SQL or invent one
- entity validation, so a fabricated customer is an error rather than an empty result
- aggregation in SQL, never in the model
- refusals instead of improvisation when a question maps to no operation
resource_linkentries identifying every record touched- a hash-chained, server-side provenance log of every call
What it does NOT give you: clickable claim-level citations. Over plain MCP the framework receives structuredContent and resource links, and then its own model composes the answer — at which point the binding between a specific claim and its evidence is gone, and the numbers pass back through generated tokens.
Preserving that binding is host-side work, because nothing in the protocol carries it. src/web.ts and src/public/index.html are the reference implementation: claim spans, citation chips, record resolution. Roughly 200 lines. Port that to your host and you get the other half.
Try these in the demo
| Question | What it shows |
|---|---|
| How much does Bergmann owe? | Every figure clickable to the invoice behind it |
| Is Bergmann Logistik at risk? | An interpretation with separately cited premises |
| Show me the receivables aging | Portfolio aggregation, computed in SQL |
| How much does Acme Corporation owe? | Fabricated entity → refusal with real alternatives |
| What will revenue be next quarter? | Unroutable → refusal rather than improvisation |
Toggle "show what this looks like when the model produces the numbers itself" for the contrast: identical formatting, fluent prose, every figure wrong, nothing in the output marking which.
Layout
migrations/001_init.sql schema + seed, shared by both backends and Docker
src/database.ts the Db seam — SqliteDb and PostgresDb behind one interface
src/db.ts opens the ERP database, applies the migration
src/operations.ts the catalog — the model's entire callable surface
src/compose.ts slot-filling; claims and spans are emitted here
src/provenance.ts append-only hash-chained store, export, verification
src/mcp-server.ts MCP server over stdio
src/web.ts demo host application
src/verify.ts npm run verify / npm run export
src/check.ts npm run check — pre-flight against a customer database
test/run.ts 30 tests covering the invariants above (32 on Postgres)
docker-compose.yml Postgres 17, seeded from the same migration
Only operations.ts writes ERP SQL, in one dialect, with ? placeholders.
PostgresDb rewrites those to $1..$n, and the single expression that genuinely
differs between the engines — whole days between two dates, julianday() on
SQLite, date subtraction on Postgres — is named daysBetween on the Db
interface rather than inlined. That is the one place a port can silently change
a number, so it is isolated and the suite asserts the same day counts on both.
Status and limits
v0, and honest about scope.
- You cannot add provenance to someone else's AI. If the answer comes from SAP Joule or Dynamics Copilot, you have no access to their retrieval pipeline or rendering. This approach applies to AI layers you build yourself over business data.
- Vendor citations exist but stop short. As of August 2026, SAP, Microsoft, NetSuite and Salesforce all ship citations that resolve to knowledge content — help articles, PDFs, documentation. None ships a general mechanism binding a figure to the transaction behind it. Numeric answers are the weakest link everywhere.
- The demo's intent routing is deliberately naive keyword matching, so the project runs with no API key. In a real deployment the model emits the tool call and this code still fills the slots. The architecture is the point, not the routing.
- Writes are out of scope. In an ERP a fabricated read is embarrassing; a fabricated write corrupts a ledger. Writes belong behind a proposal → validation → confirmation flow.
- Retention, access control, and a real deep-link resolver for a specific ERP are the last mile — and the last mile is where the actual product lives.
Prior art worth knowing
- OpenTelemetry GenAI semantic conventions — spans for GenAI clients and MCP. Early; stops well above record-level provenance.
- OpenLineage — dataset and job lineage. Same idea one layer down, for tables rather than claims.
- LLM observability — Langfuse, LangSmith, Arize, Datadog. Tracing for engineers debugging apps, not provenance for the person reading the answer.
License
MIT.
footnote MCP 질문
footnote MCP를 Claude Code에 추가하려면 어떻게 하나요?
터미널에서 claude mcp add --env 'DATABASE_URL=<YOUR_DATABASE_URL>' footnote -- npx -y @brick-byte/footnote를 실행합니다. 모든 프로젝트에서 사용할 수 있게 하려면 --scope user를 추가합니다.
footnote MCP를 Cursor에 추가하려면 어떻게 하나요?
~/.cursor/mcp.json를 열고 mcpServers 아래에 서버를 추가합니다. 위 설치 섹션에 표시된 Cursor 구성을 사용합니다.
footnote는 어떻게 환각 현상을 방지하나요?
모델이 직접 숫자를 생성하지 않도록 보장합니다. 대신 구조화된 데이터베이스 출력값을 템플릿 슬롯에 그대로 복사하여 사용합니다.
서버가 기존 ERP 데이터베이스를 수정할 수 있나요?
아니요, 서버는 세션 수준에서 읽기 전용 역할을 사용하며, 시스템에 쓰거나 손상을 입히지 않도록 문 실행 제한 시간(statement timeout)을 강제합니다.
감사 추적(audit trail)은 어디에 저장되나요?
출처 로그(provenance log)는 감사 대상 시스템과 분리될 수 있도록 별도의 추가 전용(append-only) 데이터베이스에 저장됩니다.
출처 로그는 안전한가요?
네, 각 레코드가 이전 레코드의 해시를 포함하므로 로그 조작 여부를 확인할 수 있습니다.