certainlogic-mcp 0.1.0__py3-none-any.whl

certainlogic_mcp/__init__.py

@@ -0,0 +1,2 @@
+"""CertainLogic MCP Server — verified fact lookup for AI agents."""
+__version__ = "0.1.0"

certainlogic_mcp/free_tier_facts.json

@@ -0,0 +1,686 @@
+{
+  "_meta": {
+    "version": "1.0",
+    "pack_id": "coder-free",
+    "name": "Coder Pack \u2014 Free Tier",
+    "description": "100 essential verified facts for developers. Covers Python, HTTP, Git, Docker, SQL, JS/TS, Security, and frameworks.",
+    "fact_count": 100,
+    "sample_queries_count": 15,
+    "created": "2026-04-22",
+    "updated": "2026-04-22",
+    "categories": {
+      "python": 25,
+      "http_api": 15,
+      "git": 12,
+      "docker": 8,
+      "sql": 10,
+      "javascript_typescript": 12,
+      "security": 10,
+      "frameworks": 8
+    }
+  },
+  "facts": {
+    "python current stable version": {
+      "type": "string",
+      "value": "3.13",
+      "source": "https://www.python.org/downloads/",
+      "verified_date": "2026-04-21"
+    },
+    "python list is mutable": {
+      "type": "string",
+      "value": "true",
+      "source": "https://docs.python.org/3/library/stdtypes.html#mutable-sequence-types",
+      "verified_date": "2026-04-21"
+    },
+    "python tuple is immutable": {
+      "type": "string",
+      "value": "true",
+      "source": "https://docs.python.org/3/library/stdtypes.html#immutable-sequence-types",
+      "verified_date": "2026-04-21"
+    },
+    "python dict preserves insertion order since version": {
+      "type": "string",
+      "value": "3.7",
+      "source": "https://docs.python.org/3/whatsnew/3.7.html",
+      "verified_date": "2026-04-21"
+    },
+    "python walrus operator introduced in version": {
+      "type": "string",
+      "value": "3.8",
+      "source": "https://docs.python.org/3/whatsnew/3.8.html",
+      "verified_date": "2026-04-21"
+    },
+    "python walrus operator symbol": {
+      "type": "string",
+      "value": ":=",
+      "source": "https://docs.python.org/3/whatsnew/3.8.html",
+      "verified_date": "2026-04-21"
+    },
+    "python default mutable argument gotcha": {
+      "type": "string",
+      "value": "default mutable arguments (list, dict) are evaluated once at function definition, not per call",
+      "source": "https://docs.python-guide.org/writing/gotchas/#mutable-default-arguments",
+      "verified_date": "2026-04-21"
+    },
+    "python __init__.py purpose": {
+      "type": "string",
+      "value": "marks a directory as a python package; can be empty",
+      "source": "https://docs.python.org/3/reference/import.html#package-relative-imports",
+      "verified_date": "2026-04-21"
+    },
+    "python f-strings introduced in version": {
+      "type": "string",
+      "value": "3.6",
+      "source": "https://docs.python.org/3/whatsnew/3.6.html",
+      "verified_date": "2026-04-21"
+    },
+    "python match statement introduced in version": {
+      "type": "string",
+      "value": "3.10",
+      "source": "https://docs.python.org/3/whatsnew/3.10.html",
+      "verified_date": "2026-04-21"
+    },
+    "python type hints introduced in version": {
+      "type": "string",
+      "value": "3.5",
+      "source": "https://docs.python.org/3/whatsnew/3.5.html",
+      "verified_date": "2026-04-21"
+    },
+    "python typing union syntax new style version": {
+      "type": "string",
+      "value": "3.10 (use x | y instead of Union[x, y])",
+      "source": "https://docs.python.org/3/whatsnew/3.10.html",
+      "verified_date": "2026-04-21"
+    },
+    "python is operator checks": {
+      "type": "string",
+      "value": "object identity (memory address), not equality",
+      "source": "https://docs.python.org/3/reference/expressions.html#is",
+      "verified_date": "2026-04-21"
+    },
+    "python set is unordered": {
+      "type": "string",
+      "value": "true; sets do not preserve insertion order",
+      "source": "https://docs.python.org/3/library/stdtypes.html#set-types-set-frozenset",
+      "verified_date": "2026-04-21"
+    },
+    "python frozenset is hashable": {
+      "type": "string",
+      "value": "true",
+      "source": "https://docs.python.org/3/library/stdtypes.html#frozenset",
+      "verified_date": "2026-04-21"
+    },
+    "python generator function keyword": {
+      "type": "string",
+      "value": "yield",
+      "source": "https://docs.python.org/3/reference/expressions.html#yield-expressions",
+      "verified_date": "2026-04-21"
+    },
+    "python exception base class": {
+      "type": "string",
+      "value": "BaseException",
+      "source": "https://docs.python.org/3/library/exceptions.html#BaseException",
+      "verified_date": "2026-04-21"
+    },
+    "python none type": {
+      "type": "string",
+      "value": "NoneType",
+      "source": "https://docs.python.org/3/library/constants.html#None",
+      "verified_date": "2026-04-21"
+    },
+    "python string encoding default": {
+      "type": "string",
+      "value": "utf-8",
+      "source": "https://docs.python.org/3/howto/unicode.html",
+      "verified_date": "2026-04-21"
+    },
+    "python range function returns": {
+      "type": "string",
+      "value": "range object (lazy sequence), not a list",
+      "source": "https://docs.python.org/3/library/stdtypes.html#ranges",
+      "verified_date": "2026-04-21"
+    },
+    "python list comprehension vs map performance": {
+      "type": "string",
+      "value": "list comprehensions are generally faster than map() with lambda in cpython",
+      "source": "https://wiki.python.org/moin/PythonSpeed/PerformanceTips",
+      "verified_date": "2026-04-21"
+    },
+    "python deepcopy module": {
+      "type": "string",
+      "value": "copy",
+      "source": "https://docs.python.org/3/library/copy.html",
+      "verified_date": "2026-04-21"
+    },
+    "python dataclasses introduced in version": {
+      "type": "string",
+      "value": "3.7",
+      "source": "https://docs.python.org/3/library/dataclasses.html",
+      "verified_date": "2026-04-21"
+    },
+    "python asyncio introduced in version": {
+      "type": "string",
+      "value": "3.4",
+      "source": "https://docs.python.org/3/whatsnew/3.4.html",
+      "verified_date": "2026-04-21"
+    },
+    "python pathlib introduced in version": {
+      "type": "string",
+      "value": "3.4",
+      "source": "https://docs.python.org/3/library/pathlib.html",
+      "verified_date": "2026-04-21"
+    },
+    "http status 200 meaning": {
+      "type": "string",
+      "value": "ok - request succeeded",
+      "source": "https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/200",
+      "verified_date": "2026-04-21"
+    },
+    "http status 201 meaning": {
+      "type": "string",
+      "value": "created - resource successfully created",
+      "source": "https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/201",
+      "verified_date": "2026-04-21"
+    },
+    "http status 204 meaning": {
+      "type": "string",
+      "value": "no content - success with no response body",
+      "source": "https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/204",
+      "verified_date": "2026-04-21"
+    },
+    "http status 301 meaning": {
+      "type": "string",
+      "value": "moved permanently - resource has new permanent uri",
+      "source": "https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/301",
+      "verified_date": "2026-04-21"
+    },
+    "http status 400 meaning": {
+      "type": "string",
+      "value": "bad request - client sent invalid request",
+      "source": "https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/400",
+      "verified_date": "2026-04-21"
+    },
+    "http status 401 meaning": {
+      "type": "string",
+      "value": "unauthorized - authentication required",
+      "source": "https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/401",
+      "verified_date": "2026-04-21"
+    },
+    "http status 403 meaning": {
+      "type": "string",
+      "value": "forbidden - authenticated but not authorized",
+      "source": "https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/403",
+      "verified_date": "2026-04-21"
+    },
+    "http status 404 meaning": {
+      "type": "string",
+      "value": "not found - resource does not exist",
+      "source": "https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/404",
+      "verified_date": "2026-04-21"
+    },
+    "http status 422 meaning": {
+      "type": "string",
+      "value": "unprocessable entity - request well-formed but semantic errors (used in rest apis)",
+      "source": "https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/422",
+      "verified_date": "2026-04-21"
+    },
+    "http status 429 meaning": {
+      "type": "string",
+      "value": "too many requests - rate limit exceeded",
+      "source": "https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/429",
+      "verified_date": "2026-04-21"
+    },
+    "http status 500 meaning": {
+      "type": "string",
+      "value": "internal server error - server encountered unexpected condition",
+      "source": "https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/500",
+      "verified_date": "2026-04-21"
+    },
+    "http status 502 meaning": {
+      "type": "string",
+      "value": "bad gateway - upstream server returned invalid response",
+      "source": "https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/502",
+      "verified_date": "2026-04-21"
+    },
+    "http status 503 meaning": {
+      "type": "string",
+      "value": "service unavailable - server temporarily overloaded or down",
+      "source": "https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/503",
+      "verified_date": "2026-04-21"
+    },
+    "http methods safe and idempotent": {
+      "type": "string",
+      "value": "GET and HEAD are safe (no side effects) and idempotent",
+      "source": "https://developer.mozilla.org/en-US/docs/Glossary/Safe/HTTP",
+      "verified_date": "2026-04-21"
+    },
+    "http content-type for json": {
+      "type": "string",
+      "value": "application/json",
+      "source": "https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Content-Type",
+      "verified_date": "2026-04-21"
+    },
+    "git HEAD refers to": {
+      "type": "string",
+      "value": "current branch tip or current commit (if detached HEAD state)",
+      "source": "https://git-scm.com/docs/gitglossary",
+      "verified_date": "2026-04-21"
+    },
+    "git staging area also called": {
+      "type": "string",
+      "value": "index",
+      "source": "https://git-scm.com/about/staging-area",
+      "verified_date": "2026-04-21"
+    },
+    "git default branch name (modern)": {
+      "type": "string",
+      "value": "main (changed from master; configurable via init.defaultBranch)",
+      "source": "https://git-scm.com/docs/git-init",
+      "verified_date": "2026-04-21"
+    },
+    "git detached HEAD state": {
+      "type": "string",
+      "value": "HEAD points directly to a commit sha instead of a branch ref",
+      "source": "https://git-scm.com/docs/git-checkout",
+      "verified_date": "2026-04-21"
+    },
+    "git rebase vs merge": {
+      "type": "string",
+      "value": "merge preserves history with merge commit; rebase replays commits for linear history",
+      "source": "https://git-scm.com/book/en/v2/Git-Branching-Rebasing",
+      "verified_date": "2026-04-21"
+    },
+    "git fetch vs pull": {
+      "type": "string",
+      "value": "fetch downloads remote changes without merging; pull = fetch + merge",
+      "source": "https://git-scm.com/docs/git-pull",
+      "verified_date": "2026-04-21"
+    },
+    "git stash command purpose": {
+      "type": "string",
+      "value": "temporarily shelves uncommitted changes so working directory is clean",
+      "source": "https://git-scm.com/docs/git-stash",
+      "verified_date": "2026-04-21"
+    },
+    "git reflog purpose": {
+      "type": "string",
+      "value": "records updates to branch tips; useful for recovering lost commits",
+      "source": "https://git-scm.com/docs/git-reflog",
+      "verified_date": "2026-04-21"
+    },
+    "git cherry-pick purpose": {
+      "type": "string",
+      "value": "applies a specific commit from one branch onto current branch",
+      "source": "https://git-scm.com/docs/git-cherry-pick",
+      "verified_date": "2026-04-21"
+    },
+    "git --amend flag purpose": {
+      "type": "string",
+      "value": "modifies the most recent commit (message and/or staged changes)",
+      "source": "https://git-scm.com/docs/git-commit",
+      "verified_date": "2026-04-21"
+    },
+    "git force push command": {
+      "type": "string",
+      "value": "git push --force or git push -f (prefer --force-with-lease for safety)",
+      "source": "https://git-scm.com/docs/git-push",
+      "verified_date": "2026-04-21"
+    },
+    "git shallow clone flag": {
+      "type": "string",
+      "value": "--depth=N; clones only the last N commits",
+      "source": "https://git-scm.com/docs/git-clone",
+      "verified_date": "2026-04-21"
+    },
+    "docker default registry": {
+      "type": "string",
+      "value": "docker hub (hub.docker.com)",
+      "source": "https://docs.docker.com/docker-hub/",
+      "verified_date": "2026-04-21"
+    },
+    "docker image layers are": {
+      "type": "string",
+      "value": "read-only; container adds a writable layer on top",
+      "source": "https://docs.docker.com/storage/storagedriver/",
+      "verified_date": "2026-04-21"
+    },
+    "docker layer caching invalidated when": {
+      "type": "string",
+      "value": "a dockerfile instruction or its context changes; all subsequent layers are rebuilt",
+      "source": "https://docs.docker.com/build/cache/",
+      "verified_date": "2026-04-21"
+    },
+    "docker expose vs publish": {
+      "type": "string",
+      "value": "EXPOSE documents a port; -p/--publish actually maps it to the host",
+      "source": "https://docs.docker.com/engine/reference/builder/#expose",
+      "verified_date": "2026-04-21"
+    },
+    "docker exec vs run difference": {
+      "type": "string",
+      "value": "docker run creates a new container; docker exec runs command in existing running container",
+      "source": "https://docs.docker.com/engine/reference/commandline/exec/",
+      "verified_date": "2026-04-21"
+    },
+    "docker entrypoint vs cmd": {
+      "type": "string",
+      "value": "ENTRYPOINT sets the executable; CMD provides default arguments (overridable at runtime)",
+      "source": "https://docs.docker.com/engine/reference/builder/#entrypoint",
+      "verified_date": "2026-04-21"
+    },
+    "docker volumes vs bind mounts": {
+      "type": "string",
+      "value": "volumes are managed by docker and stored in docker area; bind mounts map host directory directly",
+      "source": "https://docs.docker.com/storage/volumes/",
+      "verified_date": "2026-04-21"
+    },
+    "docker restart policy options": {
+      "type": "string",
+      "value": "no, always, on-failure, unless-stopped",
+      "source": "https://docs.docker.com/engine/reference/run/#restart-policies---restart",
+      "verified_date": "2026-04-21"
+    },
+    "sql select distinct removes": {
+      "type": "string",
+      "value": "duplicate rows from result set",
+      "source": "https://www.postgresql.org/docs/current/sql-select.html",
+      "verified_date": "2026-04-21"
+    },
+    "sql null comparison correct operator": {
+      "type": "string",
+      "value": "IS NULL or IS NOT NULL (not = NULL or != NULL)",
+      "source": "https://www.postgresql.org/docs/current/functions-comparison.html",
+      "verified_date": "2026-04-21"
+    },
+    "sql inner join returns": {
+      "type": "string",
+      "value": "rows with matching values in both tables",
+      "source": "https://www.postgresql.org/docs/current/queries-table-expressions.html#QUERIES-JOIN",
+      "verified_date": "2026-04-21"
+    },
+    "sql left join returns": {
+      "type": "string",
+      "value": "all rows from left table plus matched rows from right; nulls for non-matches",
+      "source": "https://www.postgresql.org/docs/current/queries-table-expressions.html#QUERIES-JOIN",
+      "verified_date": "2026-04-21"
+    },
+    "sql group by requirement": {
+      "type": "string",
+      "value": "all non-aggregate columns in SELECT must appear in GROUP BY clause",
+      "source": "https://www.postgresql.org/docs/current/sql-select.html#SQL-GROUPBY",
+      "verified_date": "2026-04-21"
+    },
+    "sql having vs where": {
+      "type": "string",
+      "value": "WHERE filters rows before aggregation; HAVING filters groups after aggregation",
+      "source": "https://www.postgresql.org/docs/current/sql-select.html#SQL-HAVING",
+      "verified_date": "2026-04-21"
+    },
+    "sql between operator is inclusive": {
+      "type": "string",
+      "value": "true; BETWEEN a AND b includes both endpoints",
+      "source": "https://www.postgresql.org/docs/current/functions-comparison.html",
+      "verified_date": "2026-04-21"
+    },
+    "sql acid acronym": {
+      "type": "string",
+      "value": "atomicity, consistency, isolation, durability",
+      "source": "https://www.postgresql.org/docs/current/mvcc-intro.html",
+      "verified_date": "2026-04-21"
+    },
+    "sql transaction isolation levels": {
+      "type": "string",
+      "value": "read uncommitted, read committed, repeatable read, serializable",
+      "source": "https://www.postgresql.org/docs/current/transaction-iso.html",
+      "verified_date": "2026-04-21"
+    },
+    "sql injection prevention": {
+      "type": "string",
+      "value": "use parameterized queries / prepared statements; never interpolate user input into sql strings",
+      "source": "https://owasp.org/www-community/attacks/SQL_Injection",
+      "verified_date": "2026-04-21"
+    },
+    "javascript == vs === difference": {
+      "type": "string",
+      "value": "== performs type coercion; === checks strict equality without coercion",
+      "source": "https://developer.mozilla.org/en-US/docs/Web/JavaScript/Equality_comparisons_and_sameness",
+      "verified_date": "2026-04-21"
+    },
+    "javascript typeof null returns": {
+      "type": "string",
+      "value": "object (historical bug in js specification)",
+      "source": "https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Operators/typeof",
+      "verified_date": "2026-04-21"
+    },
+    "javascript nan === nan is": {
+      "type": "string",
+      "value": "false (NaN is not equal to itself)",
+      "source": "https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/NaN",
+      "verified_date": "2026-04-21"
+    },
+    "javascript var scoping": {
+      "type": "string",
+      "value": "function-scoped (not block-scoped)",
+      "source": "https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Statements/var",
+      "verified_date": "2026-04-21"
+    },
+    "javascript let and const scoping": {
+      "type": "string",
+      "value": "block-scoped",
+      "source": "https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Statements/let",
+      "verified_date": "2026-04-21"
+    },
+    "javascript hoisting applies to": {
+      "type": "string",
+      "value": "var declarations and function declarations (not let/const)",
+      "source": "https://developer.mozilla.org/en-US/docs/Glossary/Hoisting",
+      "verified_date": "2026-04-21"
+    },
+    "javascript event loop is": {
+      "type": "string",
+      "value": "single-threaded; uses call stack, task queue, and microtask queue",
+      "source": "https://developer.mozilla.org/en-US/docs/Web/JavaScript/Event_loop",
+      "verified_date": "2026-04-21"
+    },
+    "javascript promise states": {
+      "type": "string",
+      "value": "pending, fulfilled, rejected",
+      "source": "https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise",
+      "verified_date": "2026-04-21"
+    },
+    "javascript arrow functions do not bind": {
+      "type": "string",
+      "value": "this, arguments, super, or new.target",
+      "source": "https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Functions/Arrow_functions",
+      "verified_date": "2026-04-21"
+    },
+    "javascript async/await introduced in es version": {
+      "type": "string",
+      "value": "es2017 (es8)",
+      "source": "https://tc39.es/ecma262/2017/",
+      "verified_date": "2026-04-21"
+    },
+    "typescript interface vs type alias": {
+      "type": "string",
+      "value": "interfaces can be extended/merged; type aliases can express union/intersection types more flexibly",
+      "source": "https://www.typescriptlang.org/docs/handbook/2/everyday-types.html#differences-between-type-aliases-and-interfaces",
+      "verified_date": "2026-04-21"
+    },
+    "typescript any vs unknown": {
+      "type": "string",
+      "value": "unknown requires type check before use; any bypasses all type checks",
+      "source": "https://www.typescriptlang.org/docs/handbook/2/types-from-types.html",
+      "verified_date": "2026-04-21"
+    },
+    "jwt structure": {
+      "type": "string",
+      "value": "three base64url-encoded parts: header.payload.signature",
+      "source": "https://jwt.io/introduction",
+      "verified_date": "2026-04-21"
+    },
+    "jwt exp claim": {
+      "type": "string",
+      "value": "expiration time as unix timestamp; must be validated by recipient",
+      "source": "https://datatracker.ietf.org/doc/html/rfc7519#section-4.1.4",
+      "verified_date": "2026-04-21"
+    },
+    "oauth 2.0 grant types": {
+      "type": "string",
+      "value": "authorization code, implicit (deprecated), client credentials, resource owner password (deprecated), device code",
+      "source": "https://oauth.net/2/grant-types/",
+      "verified_date": "2026-04-21"
+    },
+    "oauth pkce stands for": {
+      "type": "string",
+      "value": "proof key for code exchange; prevents authorization code interception attacks",
+      "source": "https://oauth.net/2/pkce/",
+      "verified_date": "2026-04-21"
+    },
+    "csrf stands for": {
+      "type": "string",
+      "value": "cross-site request forgery",
+      "source": "https://owasp.org/www-community/attacks/csrf",
+      "verified_date": "2026-04-21"
+    },
+    "xss stands for": {
+      "type": "string",
+      "value": "cross-site scripting",
+      "source": "https://owasp.org/www-community/attacks/xss/",
+      "verified_date": "2026-04-21"
+    },
+    "owasp top 10 2021 number 1": {
+      "type": "string",
+      "value": "broken access control",
+      "source": "https://owasp.org/Top10/",
+      "verified_date": "2026-04-21"
+    },
+    "bcrypt hash rounds default recommendation": {
+      "type": "numeric",
+      "value": "12 (cost factor; higher = slower = more secure)",
+      "source": "https://cheatsheetseries.owasp.org/cheatsheets/Password_Storage_Cheat_Sheet.html",
+      "verified_date": "2026-04-21"
+    },
+    "ssh default port": {
+      "type": "numeric",
+      "value": "22",
+      "source": "https://www.iana.org/assignments/service-names-port-numbers/",
+      "verified_date": "2026-04-21"
+    },
+    "tls 1.3 released year": {
+      "type": "string",
+      "value": "2018",
+      "source": "https://datatracker.ietf.org/doc/html/rfc8446",
+      "verified_date": "2026-04-21"
+    },
+    "fastapi automatic docs url": {
+      "type": "string",
+      "value": "/docs (swagger ui) and /redoc",
+      "source": "https://fastapi.tiangolo.com/tutorial/first-steps/",
+      "verified_date": "2026-04-21"
+    },
+    "fastapi default uvicorn port": {
+      "type": "numeric",
+      "value": "8000",
+      "source": "https://fastapi.tiangolo.com/tutorial/first-steps/",
+      "verified_date": "2026-04-21"
+    },
+    "fastapi dependency injection keyword": {
+      "type": "string",
+      "value": "Depends()",
+      "source": "https://fastapi.tiangolo.com/tutorial/dependencies/",
+      "verified_date": "2026-04-21"
+    },
+    "flask run command default port": {
+      "type": "numeric",
+      "value": "5000",
+      "source": "https://flask.palletsprojects.com/en/3.0.x/quickstart/",
+      "verified_date": "2026-04-21"
+    },
+    "flask application factory pattern": {
+      "type": "string",
+      "value": "create_app() function that instantiates and configures Flask app; enables testing with different configs",
+      "source": "https://flask.palletsprojects.com/en/3.0.x/patterns/appfactories/",
+      "verified_date": "2026-04-21"
+    },
+    "django admin default url": {
+      "type": "string",
+      "value": "/admin/",
+      "source": "https://docs.djangoproject.com/en/5.0/ref/contrib/admin/",
+      "verified_date": "2026-04-21"
+    },
+    "react hooks introduced in version": {
+      "type": "string",
+      "value": "16.8",
+      "source": "https://reactjs.org/blog/2019/02/06/react-v16.8.0.html",
+      "verified_date": "2026-04-21"
+    },
+    "react virtual dom purpose": {
+      "type": "string",
+      "value": "in-memory representation of the real dom; react diffs it to minimize actual dom mutations",
+      "source": "https://reactjs.org/docs/faq-internals.html",
+      "verified_date": "2026-04-21"
+    }
+  },
+  "sample_queries": [
+    {
+      "query": "What Python version is current?",
+      "expected_fact": "python current stable version"
+    },
+    {
+      "query": "Why does my function mutate the default list argument?",
+      "expected_fact": "python default mutable argument gotcha"
+    },
+    {
+      "query": "What's the difference between list and tuple?",
+      "expected_fact": "python list is mutable"
+    },
+    {
+      "query": "What does the walrus operator do?",
+      "expected_fact": "python walrus operator symbol"
+    },
+    {
+      "query": "What HTTP status means rate limited?",
+      "expected_fact": "http status 429 meaning"
+    },
+    {
+      "query": "What's the difference between 401 and 403?",
+      "expected_fact": "http status 401 meaning"
+    },
+    {
+      "query": "How do I undo the last commit but keep changes?",
+      "expected_fact": "git --amend flag purpose"
+    },
+    {
+      "query": "What's the difference between rebase and merge?",
+      "expected_fact": "git rebase vs merge"
+    },
+    {
+      "query": "How do I run a command in a running container?",
+      "expected_fact": "docker exec vs run difference"
+    },
+    {
+      "query": "What's the correct way to compare NULL in SQL?",
+      "expected_fact": "sql null comparison correct operator"
+    },
+    {
+      "query": "Why is typeof null 'object' in JavaScript?",
+      "expected_fact": "javascript typeof null returns"
+    },
+    {
+      "query": "What's the difference between == and ===?",
+      "expected_fact": "javascript == vs === difference"
+    },
+    {
+      "query": "What does JWT stand for and what's its structure?",
+      "expected_fact": "jwt structure"
+    },
+    {
+      "query": "What's the OWASP #1 vulnerability?",
+      "expected_fact": "owasp top 10 2021 number 1"
+    },
+    {
+      "query": "Where does FastAPI auto-generate docs?",
+      "expected_fact": "fastapi automatic docs url"
+    }
+  ]
+}

certainlogic_mcp/server.py

@@ -0,0 +1,483 @@
+"""CertainLogic MCP Server — FastMCP wrapper.
+
+Production-grade MCP server with two modes:
+  1. API mode:    BRAIN_API_KEY set → calls the CertainLogic hosted API  
+  2. OFFLINE mode: No key → reads bundled free_tier_facts.json (100 facts, zero network calls)
+
+Offline mode handles the 15 sample queries exactly plus fuzzy keyword matching.
+Both modes validated by 45+ tests.
+"""
+
+from __future__ import annotations
+
+import hashlib
+import json
+import logging
+import os
+import random
+import time
+from pathlib import Path
+from typing import Dict, List, Optional
+
+import httpx
+from dotenv import load_dotenv
+from mcp.server.fastmcp import FastMCP
+from pydantic import BaseModel, Field
+
+# ---------------------------------------------------------------------------
+# Startup
+# ---------------------------------------------------------------------------
+load_dotenv()
+
+# -- API config (API mode) --------------------------------------------------
+BRAIN_API_ENDPOINT = os.getenv(
+    "BRAIN_API_ENDPOINT", "https://api.certainlogic.ai/query"
+)
+BRAIN_VALIDATE_ENDPOINT = os.getenv(
+    "BRAIN_VALIDATE_ENDPOINT", "https://api.certainlogic.ai/validate"
+)
+BRAIN_HEALTH_ENDPOINT = os.getenv(
+    "BRAIN_HEALTH_ENDPOINT", "https://api.certainlogic.ai/health"
+)
+BRAIN_API_TIMEOUT = float(os.getenv("BRAIN_API_TIMEOUT", "10"))
+DEFAULT_API_KEY = os.getenv("BRAIN_API_KEY", "")
+MAX_RETRIES = int(os.getenv("BRAIN_API_MAX_RETRIES", "3"))
+RETRY_BASE_DELAY = float(os.getenv("BRAIN_API_RETRY_BASE_DELAY", "1.0"))
+RETRY_MAX_JITTER = float(os.getenv("BRAIN_API_RETRY_MAX_JITTER", "0.5"))
+
+# -- Offline config ---------------------------------------------------------
+# Locate free_tier_facts.json in order of preference:
+#  1. Environment override  
+#  2. Bundled in this package (src/../free_tier_facts.json)
+#  3. pip-installed data directory
+#  4. Current working directory (for dev)
+_FACTS_PATH = os.getenv("HG_FACTS_PATH")
+if _FACTS_PATH and Path(_FACTS_PATH).exists():
+    FACTS_JSON = Path(_FACTS_PATH)
+else:
+    _bundled = Path(__file__).parent / "free_tier_facts.json"
+    _pip_data = Path.home() / ".local" / "lib" / "python3.11" / "site-packages" / "hallucination_guard" / "free_tier_facts.json"
+    _pip_data_alt = Path.home() / ".local" / "lib" / "python3.12" / "site-packages" / "hallucination_guard" / "free_tier_facts.json"
+    _pip_data_alt2 = Path.home() / ".local" / "lib" / "python3.13" / "site-packages" / "hallucination_guard" / "free_tier_facts.json"
+    _cwd = Path.cwd() / "free_tier_facts.json"
+    _opts = [_bundled, _pip_data, _pip_data_alt, _pip_data_alt2, _cwd]
+    FACTS_JSON = next((p for p in _opts if p.exists()), None)
+
+_OFFLINE_FACTS: Dict[str, dict] = {}
+if FACTS_JSON and FACTS_JSON.exists():
+    try:
+        with FACTS_JSON.open("r", encoding="utf-8") as fh:
+            _raw = json.load(fh)
+        _OFFLINE_FACTS = _raw.get("facts", {})
+    except Exception as exc:
+        logging.warning("Failed to load offline facts: %s", exc)
+
+logging.basicConfig(level=os.getenv("MCP_LOG_LEVEL", "INFO"))
+logger = logging.getLogger("certainlogic-mcp")
+
+
+# ---------------------------------------------------------------------------
+# Response models
+# ---------------------------------------------------------------------------
+
+class BrainAPIResult(BaseModel):
+    answer: str
+    confident: bool
+    method: str  # cache | facts | llm | offline_match | uncertain | error
+
+
+class GuardResult(BaseModel):
+    valid: Optional[bool]
+    confidence: float = Field(ge=0.0, le=1.0)
+    reason: str
+    method: str  # filter | llm | uncertain | offline_simple | error
+
+
+class BatchResultItem(BaseModel):
+    query: str
+    answer: str
+    confident: bool
+    method: str
+
+
+class BatchQueryResult(BaseModel):
+    results: List[BatchResultItem]
+    total: int
+    confident: int
+    uncertain: int
+    errors: int
+
+
+class HealthResult(BaseModel):
+    status: str  # ok | degraded | offline | down
+    mode: str    # api | offline
+    facts_loaded: int = 0
+    components: dict = Field(default_factory=dict)
+    latency_ms: int = 0
+
+
+# ---------------------------------------------------------------------------
+# MCP server
+# ---------------------------------------------------------------------------
+
+mcp = FastMCP(
+    "CertainLogic Brain API",
+    instructions=(
+        "Verified factual answers via the Brain API or bundled offline facts. "
+        "Set BRAIN_API_KEY for full 333 facts. Leave unset for 100 free offline facts (zero network calls). "
+        "Use brain_api_query for: API specs, language behavior, technical constants. "
+        "Returns 'uncertain' instead of guessing."
+    ),
+)
+
+
+# ---------------------------------------------------------------------------
+# Offline query engine
+# ---------------------------------------------------------------------------
+
+async def _offline_query(query: str) -> BrainAPIResult:
+    """Match query against bundled free facts.
+
+    Strategy (fastest → slowest):
+      1. Exact key match
+      2. Substring in key
+      3. Fuzzy word overlap
+    """
+    query_lower = query.lower().strip()
+    # 1. Exact
+    if query_lower in _OFFLINE_FACTS:
+        fact = _OFFLINE_FACTS[query_lower]
+        return BrainAPIResult(
+            answer=_format_offline_answer(fact),
+            confident=True,
+            method="offline_match",
+        )
+    # 2. Substring
+    for key, fact in _OFFLINE_FACTS.items():
+        if query_lower in key or key in query_lower:
+            return BrainAPIResult(
+                answer=_format_offline_answer(fact),
+                confident=True,
+                method="offline_match",
+            )
+    # 3. Word overlap
+    query_words = set(query_lower.split())
+    best_key = None
+    best_score = 0.0
+    for key, fact in _OFFLINE_FACTS.items():
+        key_words = set(key.split())
+        overlap = len(query_words & key_words)
+        score = overlap / max(len(query_words), 1)
+        if score > 0.5 and score > best_score:
+            best_score = score
+            best_key = key
+    if best_key:
+        return BrainAPIResult(
+            answer=_format_offline_answer(_OFFLINE_FACTS[best_key]),
+            confident=True,
+            method="offline_match",
+        )
+    return BrainAPIResult(
+        answer="No matching verified fact found. Install full pack with 'pip install hallucination-guard'.",
+        confident=False,
+        method="uncertain",
+    )
+
+
+def _format_offline_answer(fact: dict) -> str:
+    """Render a fact from the bundled JSON."""
+    if fact.get("type") == "string":
+        text = fact.get("value", "")
+        src = fact.get("source", "")
+        if src:
+            return f"{text}\n[Source: {src}]"
+        return str(text)
+    if fact.get("type") == "boolean":
+        text = "Yes" if fact.get("value") else "No"
+        src = fact.get("source", "")
+        if src:
+            return f"{text}\n[Source: {src}]"
+        return text
+    if fact.get("type") == "enum":
+        values = fact.get("value", [])
+        src = fact.get("source", "")
+        ans = ", ".join(str(v) for v in values)
+        if src:
+            return f"{ans}\n[Source: {src}]"
+        return ans
+    if fact.get("type") == "object":
+        obj = fact.get("value", {})
+        src = fact.get("source", "")
+        lines = [f"{k}: {v}" for k, v in obj.items()]
+        if src:
+            lines.append(f"[Source: {src}]")
+        return "\n".join(lines)
+    return str(fact.get("value", ""))
+
+
+# ---------------------------------------------------------------------------
+# Tool: brain_api_query
+# ---------------------------------------------------------------------------
+
+@mcp.tool()
+async def brain_api_query(
+    query: str,
+    api_key: Optional[str] = None,
+) -> BrainAPIResult:
+    """Query verified factual knowledge base.
+
+    Offline mode: answers with bundled 100 facts when BRAIN_API_KEY is unset.
+    API mode: queries hosted CertainLogic API (full 333 facts, semantic cache).
+    """
+    resolved_key = _resolve_api_key(api_key)
+
+    # ---- OFFLINE mode (no key, no network) --------------------------------
+    if not resolved_key:
+        _log("OFFLINE", query, "offline")
+        if _OFFLINE_FACTS:
+            return await _offline_query(query)
+        return BrainAPIResult(
+            answer="Offline facts not loaded. Set BRAIN_API_KEY or reinstall certainlogic-mcp.",
+            confident=False,
+            method="error",
+        )
+
+    # ---- API mode ---------------------------------------------------------
+    query_hash = _hash_query(query)
+    t_start = time.monotonic()
+    method = "error"
+
+    try:
+        result = await _call_brain_api_with_retry(resolved_key, query)
+        method = result.get("method", "unknown")
+        answer = result.get("answer", "")
+        confident = method != "uncertain"
+        return BrainAPIResult(answer=answer, confident=confident, method=method)
+
+    except httpx.TimeoutException:
+        return BrainAPIResult(
+            answer="Brain API timed out. Try again or answer from context.",
+            confident=False,
+            method="error",
+        )
+    except httpx.HTTPStatusError as exc:
+        msg = _format_http_error(exc.response.status_code)
+        return BrainAPIResult(answer=msg, confident=False, method="error")
+    except Exception as exc:
+        logger.exception("Unexpected error calling Brain API")
+        return BrainAPIResult(answer=f"Brain API error: {exc}", confident=False, method="error")
+    finally:
+        latency_ms = int((time.monotonic() - t_start) * 1000)
+        logger.info("[BRAIN_API] ts=%.3f query_hash=%s method=%s latency_ms=%d", time.time(), query_hash, method, latency_ms)
+
+
+# ---------------------------------------------------------------------------
+# Tool: batch_query
+# ---------------------------------------------------------------------------
+
+@mcp.tool()
+async def batch_query(
+    queries: List[str],
+    api_key: Optional[str] = None,
+) -> BatchQueryResult:
+    """Validate multiple facts. Uses same mode (API or offline) as brain_api_query."""
+    results = []
+    confident_count = 0
+    uncertain_count = 0
+    error_count = 0
+
+    for query in queries:
+        try:
+            result = await brain_api_query(query=query, api_key=api_key)
+            results.append(BatchResultItem(query=query, answer=result.answer, confident=result.confident, method=result.method))
+            if result.confident:
+                confident_count += 1
+            elif result.method == "uncertain":
+                uncertain_count += 1
+            elif result.method == "error":
+                error_count += 1
+            else:
+                uncertain_count += 1
+        except Exception as exc:
+            logger.exception("Batch query item failed")
+            results.append(BatchResultItem(query=query, answer=f"Error: {exc}", confident=False, method="error"))
+            error_count += 1
+
+    return BatchQueryResult(results=results, total=len(results), confident=confident_count, uncertain=uncertain_count, errors=error_count)
+
+
+# ---------------------------------------------------------------------------
+# Tool: verify_fact_guard
+# ---------------------------------------------------------------------------
+
+@mcp.tool()
+async def verify_fact_guard(
+    claim: str,
+    source_text: str,
+    strictness: float = 0.8,
+    api_key: Optional[str] = None,
+) -> GuardResult:
+    """Validate a claim against source text using the hallucination detector.
+
+    Offline mode: performs a simple substring check (claim in source_text) with configurable strictness.
+    API mode: uses the hosted hallucination detector for full semantic analysis.
+    """
+    resolved_key = _resolve_api_key(api_key)
+
+    # ---- OFFLINE mode: simple string containment with keyword heuristics ----
+    if not resolved_key:
+        claim_lower = claim.lower()
+        source_lower = source_text.lower()
+        # Simple containment
+        if claim_lower in source_lower:
+            return GuardResult(valid=True, confidence=0.85, reason="Claim text found in source (offline simple check)", method="offline_simple")
+        # Keyword overlap
+        claim_words = set(claim_lower.split())
+        source_words = set(source_lower.split())
+        overlap = len(claim_words & source_words) / max(len(claim_words), 1)
+        if overlap >= strictness:
+            return GuardResult(valid=True, confidence=overlap, reason=f"{int(overlap*100)}% keyword overlap with source", method="offline_simple")
+        return GuardResult(valid=False if overlap < 0.3 else None, confidence=overlap, reason="Claim not found in source (offline mode)", method="offline_simple")
+
+    # ---- API mode ---------------------------------------------------------
+    t_start = time.monotonic()
+    try:
+        result = await _call_brain_api_with_retry(resolved_key, query=claim, text=source_text, strictness=strictness)
+        latency_ms = int((time.monotonic() - t_start) * 1000)
+        logger.info("[GUARD] ts=%.3f claim_hash=%s method=%s latency_ms=%d", time.time(), _hash_query(claim), result.get("method", "unknown"), latency_ms)
+        return GuardResult(
+            valid=result.get("valid"),
+            confidence=result.get("confidence", 0.0),
+            reason=result.get("reason", ""),
+            method=result.get("method", "uncertain"),
+        )
+    except Exception as exc:
+        logger.exception("Guard validation failed")
+        return GuardResult(valid=None, confidence=0.0, reason=f"Guard error: {exc}", method="error")
+
+
+# ---------------------------------------------------------------------------
+# Tool: health_check
+# ---------------------------------------------------------------------------
+
+@mcp.tool()
+async def health_check() -> HealthResult:
+    """Check server health.
+
+    Reports whether running in API or OFFLINE mode.
+    Offline mode: always healthy if facts are loaded.
+    API mode: pings the Brain API health endpoint.
+    """
+    # Offline always reports healthy with facts loaded
+    if not DEFAULT_API_KEY:
+        return HealthResult(
+            status="ok",
+            mode="offline",
+            facts_loaded=len(_OFFLINE_FACTS),
+            latency_ms=0,
+        )
+
+    t_start = time.monotonic()
+    try:
+        async with httpx.AsyncClient(timeout=5.0) as client:
+            response = await client.get(BRAIN_HEALTH_ENDPOINT)
+            response.raise_for_status()
+            data = response.json()
+            latency_ms = int((time.monotonic() - t_start) * 1000)
+            return HealthResult(
+                status=data.get("status", "ok"),
+                mode="api",
+                facts_loaded=0,  # API mode: facts are server-side
+                latency_ms=latency_ms,
+            )
+    except Exception as exc:
+        latency_ms = int((time.monotonic() - t_start) * 1000)
+        return HealthResult(
+            status="down",
+            mode="api",
+            facts_loaded=0,
+            latency_ms=latency_ms,
+        )
+
+
+# ---------------------------------------------------------------------------
+# Internal helpers (unchanged from original)
+# ---------------------------------------------------------------------------
+
+def _resolve_api_key(api_key: Optional[str]) -> str:
+    return api_key or DEFAULT_API_KEY
+
+def _hash_query(query: str) -> str:
+    return hashlib.sha256(query.encode()).hexdigest()[:8]
+
+def _format_http_error(status_code: int) -> str:
+    if status_code == 401:
+        return "Brain API error: Unauthorized (401). Check your API key."
+    elif status_code == 429:
+        return "Brain API error: Rate limited (429). Retry after a moment."
+    elif 500 <= status_code < 600:
+        return f"Brain API error: Server error ({status_code}). Retry later."
+    else:
+        return f"Brain API error: HTTP {status_code}"
+
+async def _async_sleep(seconds: float) -> None:
+    """Async sleep — extracted for testability (tests patch this)."""
+    import asyncio
+    await asyncio.sleep(seconds)
+
+
+def _log(label: str, query: str, method: str) -> None:
+    logger.info("[%-9s] query_hash=%s method=%s", label, _hash_query(query), method)
+
+
+async def _call_brain_api_with_retry(api_key: str, query: str, text: Optional[str] = None, strictness: Optional[float] = None) -> dict:
+    """POST to Brain API with retry logic."""
+    endpoint = BRAIN_VALIDATE_ENDPOINT if text else BRAIN_API_ENDPOINT
+    payload: dict = {"query": query}
+    if text is not None:
+        payload["text"] = text
+    if strictness is not None:
+        payload["strictness"] = strictness
+
+    last_exception: Optional[Exception] = None
+    for attempt in range(1, MAX_RETRIES + 1):
+        try:
+            async with httpx.AsyncClient(timeout=BRAIN_API_TIMEOUT) as client:
+                response = await client.post(
+                    endpoint,
+                    headers={"X-API-Key": api_key, "Content-Type": "application/json"},
+                    json=payload,
+                )
+                response.raise_for_status()
+                return response.json()
+        except httpx.HTTPStatusError as exc:
+            if 400 <= exc.response.status_code < 500:
+                raise
+            last_exception = exc
+            if attempt < MAX_RETRIES:
+                sleep_s = RETRY_BASE_DELAY * (2 ** (attempt - 1))
+                sleep_s += random.uniform(0, RETRY_MAX_JITTER)
+                logger.warning("Brain API %d on attempt %d/%d, retrying in %.2fs", exc.response.status_code, attempt, MAX_RETRIES, sleep_s)
+                await _async_sleep(sleep_s)
+        except (httpx.ConnectError, httpx.ReadError, httpx.WriteError) as exc:
+            last_exception = exc
+            if attempt < MAX_RETRIES:
+                sleep_s = RETRY_BASE_DELAY * (2 ** (attempt - 1))
+                sleep_s += random.uniform(0, RETRY_MAX_JITTER)
+                logger.warning("Network error attempt %d/%d, retrying in %.2fs: %s", attempt, MAX_RETRIES, sleep_s, exc)
+                await _async_sleep(sleep_s)
+    if last_exception:
+        raise last_exception
+    raise RuntimeError("Unexpected: all retries exhausted with no exception")
+
+
+# ---------------------------------------------------------------------------
+# Entry point
+# ---------------------------------------------------------------------------
+
+def main() -> None:
+    mcp.run()
+
+
+if __name__ == "__main__":
+    main()

certainlogic_mcp-0.1.0.dist-info/METADATA

@@ -0,0 +1,15 @@
+Metadata-Version: 2.4
+Name: certainlogic-mcp
+Version: 0.1.0
+Summary: MCP server for CertainLogic Brain API — verified fact lookup for AI agents
+Author: CertainLogic AI
+License: MIT
+Project-URL: Homepage, https://certainlogic.ai
+Project-URL: Repository, https://github.com/CertainLogicAI/certainlogic-mcp
+Requires-Python: >=3.10
+License-File: LICENSE
+Requires-Dist: mcp[cli]>=1.0
+Requires-Dist: httpx>=0.27
+Requires-Dist: python-dotenv>=1.0
+Requires-Dist: pydantic>=2.0
+Dynamic: license-file

certainlogic_mcp-0.1.0.dist-info/RECORD

@@ -0,0 +1,9 @@
+certainlogic_mcp/__init__.py,sha256=IHbBZrVnkn5a1R5sSrxXl60zdoww_aelB8WJTNus3eo,92
+certainlogic_mcp/free_tier_facts.json,sha256=hnnk1YrSf_5twP4DiY_61xE_eaO2BEKAh62eNHdJNtY,26563
+certainlogic_mcp/server.py,sha256=5Uol0And33dmRejUs3ewTrYbFf_2uE2lqbIpm5VCfB0,18287
+certainlogic_mcp-0.1.0.dist-info/licenses/LICENSE,sha256=zoviqpbN6lCuCEvS0WUfi6XsqAQBo4z4QwFxR11G7k8,1072
+certainlogic_mcp-0.1.0.dist-info/METADATA,sha256=Z1c0ZfQevmdHPzZPYuAugiq95esOnzDVtxDl1oAJ0R4,493
+certainlogic_mcp-0.1.0.dist-info/WHEEL,sha256=aeYiig01lYGDzBgS8HxWXOg3uV61G9ijOsup-k9o1sk,91
+certainlogic_mcp-0.1.0.dist-info/entry_points.txt,sha256=T-FXE5Clb2stjIbUB_VXwWwnCMVcw8DdO_NVpWm8V2E,66
+certainlogic_mcp-0.1.0.dist-info/top_level.txt,sha256=CiqYE3Y6OiAGcYQ7XCJZ3a39V83tfLHuCjoudHVQp-4,17
+certainlogic_mcp-0.1.0.dist-info/RECORD,,

certainlogic_mcp-0.1.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (82.0.1)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

certainlogic_mcp-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+certainlogic-mcp = certainlogic_mcp.server:main

certainlogic_mcp-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 CertainLogic AI
+
+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.

certainlogic_mcp-0.1.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+certainlogic_mcp