SEF Agents

Security Scan Python 3.13+

AI-Powered Guidance for the Synchronous Engineering Framework

SEF Agents provides agent-based AI guidance, codebase mapping, and quality enforcement for the Synchronous Engineering Framework (SEF).

Built on Anthropic's Model Context Protocol (MCP) for universal AI assistant compatibility.

What This Does
Features
Security
Installation
Configuration
Local Development
Quick Start
Contributing
About
License

What This Does

SEF Agents is an MCP server that connects to your AI assistant (Cursor, Claude Desktop, Windsurf). Once connected, it provides:

Agent-based prompts — Specialized guidance for 13 agents (10 SDLC + 3 utility)
Quality enforcement tools — Scan code for compliance, debt, security
Workflow orchestration — Track story state, dependencies, handoffs

Important: This is not a standalone app. It requires an MCP-compatible AI assistant.

Features

Agent-Based Guidance (13 Agents)

SDLC Workflow Agents (10)

Agent	Function
`discovery`	Brownfield codebase scanning, CODE_MAP generation
`product_manager`	Requirements, acceptance criteria
`qa_lead`	Validates AC before development begins
`architect`	System design, boundaries, integration points
`developer`	Elite Code Quality Protocol enforcement
`tester`	Test standards, real-execution tests
`pr_reviewer`	PR review, AI anti-pattern detection
`scrum_master`	Process orchestration, handoff tracking
`security_owner`	Security audit, vulnerability scanning
`test_designer`	Conceptual test design, BDD architecture

Utility Agents (3) — On-Demand

Agent	Function
`forensic_engineer`	Incident investigation, 5 Whys, post-mortems
`strategist`	Solution brainstorming, trade-off analysis
`platform_engineer`	DevEx, health scanning, code quality enforcement

Quality Tools

Tool	What It Does
`generate_codemap`	Auto-document directory structure
`validate_compliance`	Check code against SEF standards
`detect_ai_patterns`	Find AI-generated code smells
`scan_debt`	Detect technical debt (TODOs, bare exceptions, etc.)
`scan_external_dependencies`	Find env vars, API clients, external URLs
`scan_code_quality`	AST-based pe_rules enforcement (bare except, types, logging)
`scan_health`	Unified health report across all quality dimensions

Workflow Tools

Tool	What It Does
`init_workflow`	Start tracking a story
`get_workflow_state`	See current phase, blockers, artifacts
`suggest_next_agent`	Auto-suggest agent transitions
`generate_story_dependency_graph`	Visualize story dependencies
`detect_flow_gaps`	Find broken E2E flows

Security

SEF Agents is designed with security as a core principle:

✅ No Network Calls: Contains no HTTP clients, sockets, or external communication
✅ No Data Exfiltration: All operations are local-only
✅ No Hardcoded Secrets: Scanned for credentials and API keys
✅ Audited Dependencies: All dependencies use permissive OSS licenses
✅ Stdio Transport Only: Communication via standard input/output streams

Run Security Audit

Enterprise customers can verify these claims:

# Run full security audit
uv run python -m sef_agents.security_scan

# Output JSON for CI/CD
uv run python -m sef_agents.security_scan --format json

See SECURITY.md for full security policy and architecture details.

Installation

Prerequisites

uv or uvx (Install uv)
Python 3.12+ (Windows users: see WINDOWS_TROUBLESHOOTING.md if encountering installation issues)

Client Compatibility

SEF Agents uses stdio transport (Standard Input/Output). It works with:

Claude Desktop
Cursor
Windsurf
Any MCP-compatible client supporting stdio

Note: Gemini and GitHub Copilot do not currently support MCP.

Configuration

Simple installation — works like Playwright MCP. No cloning required.

Cursor (Recommended)

Add to ~/.cursor/mcp.json (global) or .cursor/mcp.json (project-local):

{
  "mcpServers": {
    "sef-agents": {
      "command": "uvx",
      "args": ["sef-agents"]
    }
  }
}

Via UI:

Settings → MCP → + Add New MCP Server
Name: sef-agents
Type: command
Command: uvx sef-agents

Claude Desktop

Add to claude_desktop_config.json:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "sef-agents": {
      "command": "uvx",
      "args": ["sef-agents"]
    }
  }
}

Windsurf

Add to ~/.codeium/windsurf/mcp_config.json:

{
  "mcpServers": {
    "sef-agents": {
      "command": "uvx",
      "args": ["sef-agents"]
    }
  }
}

How `uvx` Resolves the Package

uvx sef-agents requires no prior installation. Here's what happens:

uvx receives the package name sef-agents
Queries PyPI (https://pypi.org/simple/) — the default registry, same as pip
Downloads the latest wheel into an isolated temporary environment
Runs the sef-agents entry point
Nothing persists in your global Python environment

You only need uv installed. The package is fetched on demand.

To pin a specific version:

{
  "mcpServers": {
    "sef-agents": {
      "command": "uvx",
      "args": ["sef-agents==3.15.0"]
    }
  }
}

Install from GitHub (Development/Unpublished)

If not yet published to PyPI, use GitHub:

{
  "mcpServers": {
    "sef-agents": {
      "command": "uvx",
      "args": [
        "--from",
        "git+https://github.com/Mishtert/sef-agents",
        "sef-agents"
      ]
    }
  }
}

Note for Windows users: If you encounter pywin32 access denied errors, see WINDOWS_TROUBLESHOOTING.md for solutions. Prefer using PyPI version (uvx sef-agents) when available.

Local Development

For contributors or local testing:

git clone https://github.com/Mishtert/sef-agents.git
cd sef-agents
uv sync
uv run sef-agents

Quick Start

1. Verify Connection

After adding the config, restart your AI assistant. In Cursor:

Open Settings → MCP
Look for sef-agents with a green status indicator

2. Try These Commands

Type these in your AI assistant to verify it's working:

"What SEF agents are available?"

Expected: List of 13 agents with descriptions.

"Set my agent to developer"

Expected: Elite Code Quality Protocol injected. AI now enforces coding standards.

"Generate a codemap for this directory"

Expected: CODE_MAP.md structure with files, purposes, dependencies.

"Scan this directory for technical debt"

Expected: Report of TODOs, bare exceptions, missing types, long functions.

3. Full Workflow Example

1. "Set agent to discovery" → Scans codebase, generates documentation
2. "Set agent to product_manager" → Write requirements with testable AC
3. "Set agent to qa_lead" → Validate AC before development
4. "Set agent to developer" → Implement with quality enforcement
5. "Set agent to pr_reviewer" → Review for compliance + AI patterns

Troubleshooting

Issue	Solution
MCP not connecting	Restart AI assistant after config change
`uvx` not found	Install uv: `curl -LsSf https://astral.sh/uv/install.sh \| sh`
Tools not appearing	Check MCP status in settings; verify JSON syntax
Agent not activating	Use exact agent name: `developer`

Contributing

We welcome contributions! Please see CONTRIBUTING.md for:

Code of conduct
Development setup
PR submission guidelines
Testing requirements

Version History: See GitHub Releases for changelog.

About

SEF Agents implements the Model Context Protocol (MCP), an open standard developed by Anthropic for connecting AI assistants to external tools and data sources. This ensures compatibility with a wide ecosystem of AI development tools.

SEF Agents is part of the Synchronous Engineering Framework (SEF) — a methodology for collapsing the software delivery lifecycle through intelligent parallelism and agent orchestration.

License

Metadata

Release files for sef-agents 4.3.25

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for sef-agents 4.3.25
File	Size	Uploaded
sef_agents-4.3.25.tar.gz	812.5 kB	Jul 21, 2026	Details

Built distribution (wheel)

Table of built distributions (wheels) for sef-agents 4.3.25
File	Interpreter	ABI	Platform	Reset
sef_agents-4.3.25-py3-none-any.whl 489.5 kB Jul 21, 2026	Python 3	none	any	Details

Total release size: 1.3 MB

Release files / sef_agents-4.3.25.tar.gz

Download URL	sef_agents-4.3.25.tar.gz
Size	812.5 kB
Tags	Source
SHA-256 checksum How to use checksums	`b5bc6a2eda51b0cfc2760c341ef788ab74db49b7c54ac8bd87ac230c056a0e29`
BLAKE2b-256 checksum How to use checksums	`95a757bcfe77ccecb867bc68b5655ccd351f48bde4e86bfa9314fb2cb452b7cc`
Upload date	Jul 21, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	Yes
Uploaded via	`twine/6.1.0 CPython/3.13.14`

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

Identity

Publishing platform: GitHub Actions
Publishing repository: github.com/Mishtert/sef-agents
Publishing commit: github.com/Mishtert/sef-agents/tree/288a099ea7f5d259619827720fbbb53243334896

Workflow

Publishing configuration: github.com/Mishtert/sef-agents/blob/288a099ea7f5d259619827720fbbb53243334896/.github/workflows/publish.yml
Publishing logs: github.com/Mishtert/sef-agents/actions/runs/29814240115/attempts/1

Artifact

Subject: sef_agents-4.3.25.tar.gz
SHA-256 checksum: b5bc6a2eda51b0cfc2760c341ef788ab74db49b7c54ac8bd87ac230c056a0e29 Verifying attestations

Release files / sef_agents-4.3.25-py3-none-any.whl

Download URL	sef_agents-4.3.25-py3-none-any.whl
Size	489.5 kB
Tags	Python 3
SHA-256 checksum How to use checksums	`4955d8d657775dc5c5863a792bb60b4324775889b09aa606f50e75a1feeee7b4`
BLAKE2b-256 checksum How to use checksums	`00af30040eaa80ad6c489643b69a5c43b815612194af35b63813aefa6b40a90c`
Upload date	Jul 21, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	Yes
Uploaded via	`twine/6.1.0 CPython/3.13.14`

Provenance

Identity

Publishing platform: GitHub Actions
Publishing repository: github.com/Mishtert/sef-agents
Publishing commit: github.com/Mishtert/sef-agents/tree/288a099ea7f5d259619827720fbbb53243334896

Workflow

Publishing configuration: github.com/Mishtert/sef-agents/blob/288a099ea7f5d259619827720fbbb53243334896/.github/workflows/publish.yml
Publishing logs: github.com/Mishtert/sef-agents/actions/runs/29814240115/attempts/1

Artifact

Subject: sef_agents-4.3.25-py3-none-any.whl
SHA-256 checksum: 4955d8d657775dc5c5863a792bb60b4324775889b09aa606f50e75a1feeee7b4 Verifying attestations