Skip to main content
Glama
dogrucanemek-alt

tugra

by dogrucanemek-alt
OverviewSchemaRelated ServersScoreDiscussions
TypeScript
Local

tugra

npx tugra init

That creates a vault, writes a sample fact, and prints a config block. Paste the block into your MCP client. On a TTY, npx tugra prints help and exits. Piped (Claude Desktop, Cursor, Claude Code) it is the MCP server.

Provenance-aware memory for AI agents. Every claim carries its source, its age, and its boundary. There is no cloud.

What it is

A fact that cannot name where it came from is not a fact. Tugra stores each claim as a file whose frontmatter holds source, last verification date, shelf life, and — when the topic is off-limits — a boundary that forbids invention. Search ranks by token score, then freshness, then confidence. Retired and rotten facts stay out of the default set.

Related MCP server: AgentBase

Tools

Tool

What it does

fact_search

Search the vault. Retired/rotten omitted unless archive: true.

fact_read

Read one fact by uid. Body is escaped before the model sees it.

fact_propose

Write a draft. Secret patterns are rejected before any write. type: "boundary" is always quarantined.

event_report

Append a local telemetry line. No network.

Stored field names stay in the vault's native shape (kaynak, guven, raf_omru, sinir). The tool names and parameter names above are the public contract.

Install — env paths (optional)

tugra init is enough to start. Override the two paths only if you already have a vault elsewhere. Without them, the server looks next to the installed package — that is wrong for a bare npx with no init.

  • TUGRA_KASA — vault (markdown facts)

  • TUGRA_AKIS — telemetry directory

Authorization: if no authorization store is configured, single-user mode is on — search and propose work without a profile. If an authorization store is configured (a yetki/ directory, or TUGRA_YETKI), each agent needs a JSON profile or search returns unauthorized.

Claude Desktop

claude_desktop_config.json:

{
  "mcpServers": {
    "tugra": {
      "command": "npx",
      "args": ["-y", "tugra"],
      "env": {
        "TUGRA_KASA": "/absolute/path/to/vault",
        "TUGRA_AKIS": "/absolute/path/to/events"
      }
    }
  }
}

Claude Code

.mcp.json at the project root, or claude mcp add:

{
  "mcpServers": {
    "tugra": {
      "command": "npx",
      "args": ["-y", "tugra"],
      "env": {
        "TUGRA_KASA": "/absolute/path/to/vault",
        "TUGRA_AKIS": "/absolute/path/to/events"
      }
    }
  }
}

Cursor

.cursor/mcp.json or Cursor Settings → MCP:

{
  "mcpServers": {
    "tugra": {
      "command": "npx",
      "args": ["-y", "tugra"],
      "env": {
        "TUGRA_KASA": "/absolute/path/to/vault",
        "TUGRA_AKIS": "/absolute/path/to/events"
      }
    }
  }
}

Windsurf

mcp_config.json:

{
  "mcpServers": {
    "tugra": {
      "command": "npx",
      "args": ["-y", "tugra"],
      "env": {
        "TUGRA_KASA": "/absolute/path/to/vault",
        "TUGRA_AKIS": "/absolute/path/to/events"
      }
    }
  }
}

Codex

~/.codex/config.toml:

[mcp_servers.tugra]
command = "npx"
args = ["-y", "tugra"]

[mcp_servers.tugra.env]
TUGRA_KASA = "/absolute/path/to/vault"
TUGRA_AKIS = "/absolute/path/to/events"

Windows: use a full path (C:\\Users\\…\\vault). Node 20 or newer.

More client notes: docs/install.md.

Shared-vault authorization (optional)

Single-user setups do not need this. Add TUGRA_YETKI only when several agents share one vault and each needs its own profile (mcp-readonly@tugra and others as JSON files in that directory). A missing profile then returns unauthorized. An empty TUGRA_YETKI is treated as unset — single-user mode stays on.

Host library surface (not the MCP wire)

The MCP tools (fact_search, fact_read, fact_propose, event_report) enforce authorization on every call. The published package also ships dist-paket/akis.js and dist-paket/yetki.js so a host application (cron, mirror, cockpit) can write telemetry without going through JSON-RPC.

Those modules are public on purpose. akisBildir({ atlaYetki: true }), eylem: "yetki_talebi", and dosyaYoksaIzin (default true) skip or relax the check. harcamaEkle mutates a profile. The host that imports them owns authorization. The MCP wire cannot set these flags — the tool schema does not accept them.

Scale vault vs target vault

A0–A5 levels are facts (yonetisim.yetki.a0 … a5) in a vault. The stdio server reads them from TUGRA_KASA, or from the cockpit kasa/ when that variable is unset.

tugraArac / createTugraMcp take an optional kasaKok (the write/search target). Scale does not follow that target. It defaults to varsayilanKasa() — the same central vault the stdio server uses. A host that points kasaKok at a data-only tree keeps using the cockpit / TUGRA_KASA scale. To read scale from a different tree, pass skalaKasa explicitly.

All four tools share one resolver. This is the contract: separate target + central governance stays reachable. YAYIN/12 briefly defaulted scale to kasaKok; that broke the split-root host. YAYIN/13 restores the central default.

What we do not guarantee

  • No cloud sync. The vault is the files you pointed at. Nothing is uploaded.

  • No automatic merge. Two writers, two files. You reconcile.

  • No delete in this release. Retirement exists; erasure is later.

  • No automatic conflict detection. Contradictory facts can sit side by side until a human says otherwise.

  • No hosted service. npx tugra is a local stdio process.

This package is not published as a SaaS. There is no price table here.

Requirements

  • Node.js 20 or newer. This is a support decision, not a technical floor: the package is tested on 20 and 22 in CI, and it also runs on 18 — but 18 is past its end of life, so we do not support it.

  • A vault directory you own

Topic map (optional)

<vault>/_konu-haritasi.json — { "desen", "bayrak", "konu" } rules in harita, alt_kirilim, and stem. If the file is missing the map is empty: unknown text falls back to kurum.genel or dunya.<world>.genel. Broken or over-long patterns are skipped and logged. This package does not ship a company taxonomy.

License

Apache-2.0. See LICENSE and NOTICE.

The marketing page lives in ../site/ (npm run preview there). It is not deployed from this package.

Compatibility: TALAMUS_* and MULTI_* names still work as fallback if TUGRA_* is unset.

Available Tools

4 tools
event_reportB

Append a telemetry line to akis/YYYY-MM-DD.jsonl. No network.

ParametersJSON Schema
NameRequiredDescriptionDefault
jobYes
noteNo
agentYes
worldNo
actionYes
statusYes
blockedNo
touchedNo
confidenceNo

TDQS

B3.3/5.0
Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

There are no annotations, so the description carries the full burden. It discloses that the operation is an append (non-destructive), writes to a dated local file, and is network-free ('No network.'). However, it does not explain return values, error behavior, file creation, or whether appends are atomic, which are relevant for a mutation tool with no annotation support.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is two short sentences with no filler. The primary action and destination are front-loaded, and the extra 'No network.' sentence adds distinct behavioral value without redundancy.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness2/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool has nine parameters, no annotations, no output schema, and 0% schema description coverage, this minimal description is not enough. An agent would still be uncertain about required field semantics, how to construct a valid telemetry line, and what happens after the append.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters2/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 0%, so the description must compensate, but it does not explain any of the nine parameters. The phrase 'telemetry line' provides only a general context; the agent still gets no help understanding fields like 'blocked,' 'touched,' or 'confidence' beyond their names and enums.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description uses a specific verb and resource: 'Append a telemetry line to akis/YYYY-MM-DD.jsonl.' This clearly distinguishes the tool from the fact-oriented siblings (fact_search, fact_read, fact_propose) by indicating it is for telemetry recording, not fact operations.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description gives no explicit guidance on when to use this tool versus the sibling tools. It does not state that this is for reporting events as opposed to reading facts, nor does it mention conditions, exclusions, or alternatives. Usage must be inferred entirely from the tool name and the word 'telemetry.'

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

fact_proposeA

Write a draft fact under kasa/_oneriler/ (or quarantine). Secret patterns are rejected before any write; the matching text is never returned. type=boundary is always quarantined. Fake mcp:// sources are not injected.

ParametersJSON Schema
NameRequiredDescriptionDefault
bodyYes
typeNostored as tur; boundary is always quarantined
agentYesauthorization agent id
titleYes
topicNo
worldNo
sourceNoreal evidence; if omitted, kaynak is written empty — mcp:// is not injected

TDQS

A3.9/5.0
Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations available, the description carries the full burden and does well: it discloses that secret patterns are rejected before any write, matching text is never returned, type=boundary is always quarantined, and fake mcp:// sources are not injected. These are non-obvious behaviors an agent could not infer from the schema or tool name. Some gaps remain around authentication failures and persistence guarantees, but the most important safety behavior is covered.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Three dense, information-bearing sentences with the operation front-loaded and constraints following. There is no filler, repetition of schema fields, or unnecessary background. Every sentence adds either operational meaning or safety-critical context.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a 7-parameter mutation tool with no annotations and no output schema, the description covers the most critical write-path safety rules and destination details. However, it omits usage-selection guidance, return behavior, and the meaning of several optional fields, leaving the agent somewhat undersupplied for a fully confident invocation.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is only 43%, so the description must compensate. It adds meaningful context for type (boundary is always quarantined) and source (real evidence only, no mcp:// injection), but title, body, topic, world, and agent semantics are left mostly to inference. This is partial compensation, not full coverage of the parameter space.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb and resource: 'Write a draft fact under kasa/_oneriler/ (or quarantine)'. This clearly distinguishes the tool from siblings fact_search, fact_read, and event_report, which are read/search/report operations. The write operation and destination path leave no ambiguity about what the tool does.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description implies the tool is for writing facts by using the verb 'Write', but it never explicitly says when to prefer this over fact_search, fact_read, or event_report, nor when not to use it. It provides behavioral constraints rather than selection criteria, so usage guidance is implied rather than explicit.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

fact_readA

Read one fact by uid. Body passes through the presentation layer (injection escaping). Retired facts include superseded_by and the reason.

ParametersJSON Schema
NameRequiredDescriptionDefault
uidYes
agentNoauthorization agent id (default mcp-readonly@tugra)

TDQS

A3.5/5.0
Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations provided, the description carries the full burden. It does add useful context about body escaping and retired-fact fields, which is beyond the bare 'read' meaning. However, it omits behavior for missing facts, errors, authorization requirements, or response shape.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Two sentences, with the core action front-loaded and no wasted words. The behavioral note about escaping and retired facts earns its place.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a simple single-fact read tool, the description covers key lookup semantics and a special retired-fact case. But with no output schema and no annotation, it does not describe what happens when the uid is invalid or the result is empty, and it fails to mention when to choose fact_search instead.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 50%: agent is documented but uid is not. The description adds some meaning by indicating the uid identifies the fact to read, but it does not elaborate on uid format or the agent parameter beyond what the schema already says.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description states a clear verb and resource: 'Read one fact by uid.' It identifies the exact lookup method (by uid), which distinguishes it from fact_search, though it does not explicitly name siblings or contrast them.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description implies the tool is used when you have a fact's uid, but provides no explicit guidance on when to prefer fact_search or the other siblings. It does not state alternatives or exclusions, leaving the routing decision to inference.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Install Server
RayrunBuild, deploy, and operate MCP servers without becoming an infrastructure team.ray.runAd

TDQS

A3.8/5.0
Disambiguation5/5

Each tool targets a distinct operation: searching facts, reading by UID, proposing a draft fact, and appending telemetry. There is no meaningful overlap between fact_search, fact_read, fact_propose, and event_report.

Naming Consistency5/5

All tool names use lowercase snake_case and an object-first pattern (fact_search, fact_read, fact_propose, event_report). Although event_report lacks the fact_ prefix, it follows the same noun-verb shape, making the naming predictable and consistent.

Tool Count5/5

Four tools is a well-scoped surface for a fact-store server: two retrieval paths, one proposal/write path, and one telemetry path. Each tool earns its place without redundancy or bloat.

Completeness4/5

The search/read/propose set covers the main fact consumption and contribution workflows. Direct lifecycle operations such as update, retire, or approve are absent, but the proposal mechanism and archive flag suggest a curated interface where this is an acceptable minor gap.

Maintenance

ActivityMaintained
ResponsivenessSyncing

Resources

Related MCP Connectors

Related MCP Servers

  • Librarian

    arcadeai-labs
    A
    license
    Not graded
    quality
    A
    maintenance
    Provides AI agents with persistent knowledge storage, enabling them to store, search, and retrieve text, documents, and files using semantic and keyword search via MCP tools.
    32
    Apache 2.0

  • AgentBase

    vhspace
    A
    license
    Not graded
    quality
    D
    maintenance
    Enables AI agents to persistently store and semantically search shared knowledge via MCP tools.
    2
    MIT
  • CarpeOS MCP Server by innocarpe

    CarpeOS MCP Serverofficial

    innocarpe
    A
    license
    Not graded
    quality
    A
    maintenance
    Enables AI agents to capture, search, and manage structured memory from agent sessions with append-only events and provenance tracking, providing eight local MCP stdio tools.
    Apache 2.0

  • @memharness/mcp

    las7
    A
    license
    Not graded
    quality
    A
    maintenance
    A bi-temporal, provenance-carrying memory primitive for AI agents. Enables storing facts, recall, revision, and audit trails via MCP with SQLite storage.
    6
    Apache 2.0

Latest Blog Posts

MCP directory API

We provide all the information about MCP servers via our MCP API.

curl -X GET 'https://glama.ai/api/mcp/v1/servers/dogrucanemek-alt/tugra'

If you have feedback or need assistance with the MCP directory API, please join our Discord server