Sufler

An MCP server and agent runtime built for one team: a shared, searchable knowledge base of project notes and status, reachable from Claude Code, Microsoft Teams, a command line and GitHub. Meeting notes and project status go into one store instead of scattered files, GitHub and Teams exchange events, and Jira answers "what are my open tasks" without leaving the conversation.

About this copy. I built Sufler during my internship at BIAP (Intelligent Technologies division, July to September 2026) and publish it with the company's consent. Personal data and company infrastructure (hosts, tenant, team and channel identifiers) were removed from every commit, and #N in commit messages refers to pull requests in the private original. The documentation under docs/ is in Polish.

Status

Deployed as a pilot in one team. The code of phases 1 to 4 is complete: the MCP server, the agent runtime, the Teams, CLI and GitHub entry points, the GitHub ↔ event store ↔ Teams bridge with gated writes, read-only Jira, the Teams Shifts schedule and lexical retrieval over notes. Open: the HTTP deployment (docs/roadmap.md).

Related MCP server: ContextForge

Architecture

One core, several entry points. All logic lives in a core with no I/O (core/); Claude Code over MCP, Teams, the CLI and GitHub are thin adapters over the same tool catalogue, so a new tool is written once. The core never imports an adapter, and import-linter checks that in CI.

Quick start

Requires Python 3.11 and uv.

uv sync                               # core; the MCP server runs on local files with no secrets
uv run sufler                         # MCP server (stdio)
uv run mcp dev src/sufler/server.py   # inspect the tools

Details

Both MCP tool counts, five frozen and three additive, are held by the golden test tests/adapters/test_mcp_tool_surface.py. The agent has eight tools with the shell enabled and fourteen without it; the full set, each tool's actions and a byte ceiling on tool descriptions are held by tests/core/test_tool_descriptions.py.

• Jira is read-only. It does not create issues, comment or change status; there is no write path in the code, and the Jira account never comes from the model.

• Writes are off by default everywhere. Code for a mutating capability can be in the tree and still be unreachable until an operator opens its gate. tests/test_gates_closed_by_default.py finds the gates by reflection and checks the configuration templates too.

• The HTTP entry point does not write. The streamable-http transport forces writes off regardless of configuration and does not expose Jira tools (ADR 0007).

• The MCP tool surface is frozen. A new tool there breaks the golden test and needs an ADR first.

• Meeting and thread notes are immutable; immutability is how idempotency works here.

• Dense retrieval is built but switched off until it passes the evaluation gate (ADR 0039).

src/sufler/
├── core/            # no I/O, no SDKs
│   ├── domain/      # models and pure logic
│   ├── ports/       # interfaces (repositories, LLM, GitHub, Jira, notifications)
│   ├── application/ # use cases and the single tool catalogue
│   └── agent/       # agent runtime
├── adapters/
│   ├── inbound/     # entry points: mcp, teams, teams_graph, cli, github
│   └── outbound/    # clients of external APIs
├── server.py        # MCP server wiring
└── config/          # SUFLER_* settings, one module per domain

The bridge connects GitHub, a shared append-only event store with deduplication, and Teams; no component calls another directly. Jira is not part of the bridge: "my tasks" is a direct, read-only query scoped to the asking user's account. Diagrams: docs/explanation/architecture.md.

The repository ships a project-scoped .mcp.json, so Claude Code opened in this directory picks up the sufler server. save_note is off by default; copy .env.example to .env to enable it locally. Other entry points need extras (uv sync --extra <name>): agent, teams, teams-graph, github, jira, retrieval, retrieval-dense, file-reply, seed. The full list of console scripts and settings is in docs/reference/ and docs/how-to/gate-matrix.md.

uv run --no-sync pytest
uv run --no-sync ruff check src tests eval deploy scripts
uv run --no-sync ruff format --check src tests eval deploy scripts
uv run --no-sync mypy
uv run --no-sync lint-imports      # core must not import adapters

This is the same gate CI runs (.github/workflows/ci.yml). The sub-projects have their own environments and are tested separately. A security suite covers injection, path traversal and secret leakage (tests/security/).

• Reading is the default; every mutating capability has its own gate, off by default, opened per entry point.

• Note and event content is data, not instructions. Only control characters are rejected or stripped by code; trust classes T0 to T3 label content rather than block it (ADR 0066). The defence against prompt injection is the capability gates, read-only mounts, the network-less executor and reversibility.

• Secrets are read from the environment or files outside data/, never from the repository.

• sufler (src/, tests/, docs/, deploy/, eval/, scripts/): the core described above.

• Powiadomienia_teams/: weekly Microsoft Shifts reminders in Teams, writing shifts back only after an explicit "yes".

• claude_summary/: a CLI that summarises a person's day from Claude Code prompt history (with explicit consent) and commit history, redacting sensitive content at parse time.

• ceidg-tool/: exports data on sole proprietorships from the CEIDG register API to Excel, with a wizard and an offline --demo mode.

• krs-tool/: reads a court-register (KRS) extract saved by the operator and reports registry signals about a company; it has no network client by design.

Each sub-project has its own environment, CI entry and README.

docs/ follows Diátaxis: tutorial, how-to, reference, explanation, decision records in docs/adr/ and research notes. Changes between versions: CHANGELOG.md.

License

MIT, see LICENSE.