mcpkernel 0.1.0__tar.gz

mcpkernel-0.1.0/.github/FUNDING.yml

@@ -0,0 +1 @@
+github: [piyushptiwari1]

mcpkernel-0.1.0/.github/ISSUE_TEMPLATE/bug_report.yml

@@ -0,0 +1,97 @@
+name: Bug Report
+description: Report a bug in MCPKernel
+title: "[Bug]: "
+labels: ["bug", "triage"]
+body:
+  - type: markdown
+    attributes:
+      value: |
+        Thanks for taking the time to report a bug! Please fill in the details below.
+
+  - type: input
+    id: version
+    attributes:
+      label: MCPKernel Version
+      description: "Output of `mcpkernel --version` or commit hash"
+      placeholder: "0.1.0 or abc1234"
+    validations:
+      required: true
+
+  - type: dropdown
+    id: component
+    attributes:
+      label: Component
+      description: Which MCPKernel component is affected?
+      options:
+        - Proxy Gateway
+        - Policy Engine
+        - Taint Tracking
+        - Sandbox (Docker/Firecracker/WASM)
+        - DEE (Deterministic Execution Envelopes)
+        - Audit Logging
+        - Context Minimization
+        - eBPF
+        - Observability
+        - CLI
+        - Other
+    validations:
+      required: true
+
+  - type: textarea
+    id: description
+    attributes:
+      label: Bug Description
+      description: A clear description of what the bug is
+      placeholder: "When I do X, Y happens instead of Z"
+    validations:
+      required: true
+
+  - type: textarea
+    id: reproduce
+    attributes:
+      label: Steps to Reproduce
+      description: Minimal steps to reproduce the issue
+      value: |
+        1. 
+        2. 
+        3. 
+    validations:
+      required: true
+
+  - type: textarea
+    id: expected
+    attributes:
+      label: Expected Behavior
+      description: What should have happened?
+    validations:
+      required: true
+
+  - type: textarea
+    id: logs
+    attributes:
+      label: Logs / Error Output
+      description: Paste any relevant logs or error messages
+      render: shell
+
+  - type: dropdown
+    id: python
+    attributes:
+      label: Python Version
+      options:
+        - "3.10"
+        - "3.11"
+        - "3.12"
+    validations:
+      required: true
+
+  - type: dropdown
+    id: os
+    attributes:
+      label: Operating System
+      options:
+        - Linux
+        - macOS
+        - Windows (WSL)
+        - Other
+    validations:
+      required: true

mcpkernel-0.1.0/.github/ISSUE_TEMPLATE/config.yml

@@ -0,0 +1,8 @@
+blank_issues_enabled: false
+contact_links:
+  - name: Security Vulnerability
+    url: https://github.com/piyushptiwari1/mcpkernel/security/advisories/new
+    about: Report a security vulnerability privately via GitHub Security Advisories
+  - name: Questions & Discussion
+    url: https://github.com/piyushptiwari1/mcpkernel/discussions
+    about: Ask questions and share ideas in GitHub Discussions

mcpkernel-0.1.0/.github/ISSUE_TEMPLATE/feature_request.yml

@@ -0,0 +1,72 @@
+name: Feature Request
+description: Suggest a new feature or improvement for MCPKernel
+title: "[Feature]: "
+labels: ["enhancement"]
+body:
+  - type: markdown
+    attributes:
+      value: |
+        Thanks for suggesting an improvement! Please describe your idea below.
+
+  - type: dropdown
+    id: component
+    attributes:
+      label: Component
+      description: Which area does this feature relate to?
+      options:
+        - Proxy Gateway
+        - Policy Engine
+        - Taint Tracking
+        - Sandbox (Docker/Firecracker/WASM)
+        - DEE (Deterministic Execution Envelopes)
+        - Audit Logging
+        - Context Minimization
+        - eBPF
+        - Observability
+        - CLI
+        - New Component
+        - Documentation
+        - Other
+    validations:
+      required: true
+
+  - type: textarea
+    id: problem
+    attributes:
+      label: Problem Statement
+      description: What problem does this feature solve? Is it related to a frustration?
+      placeholder: "I'm always frustrated when..."
+    validations:
+      required: true
+
+  - type: textarea
+    id: solution
+    attributes:
+      label: Proposed Solution
+      description: How should this work? Include API examples, config snippets, or diagrams if helpful.
+    validations:
+      required: true
+
+  - type: textarea
+    id: alternatives
+    attributes:
+      label: Alternatives Considered
+      description: What other approaches did you consider?
+
+  - type: dropdown
+    id: priority
+    attributes:
+      label: Priority (your estimate)
+      options:
+        - "Nice to have"
+        - "Important"
+        - "Critical for my use case"
+    validations:
+      required: true
+
+  - type: checkboxes
+    id: contribution
+    attributes:
+      label: Contribution
+      options:
+        - label: I'm willing to submit a PR for this feature

mcpkernel-0.1.0/.github/PULL_REQUEST_TEMPLATE.md

@@ -0,0 +1,37 @@
+## Description
+
+<!-- What does this PR do? Link to the related issue if applicable. -->
+
+Fixes #
+
+## Changes
+
+<!-- List the key changes in this PR -->
+
+- 
+
+## Type of Change
+
+- [ ] Bug fix (non-breaking change that fixes an issue)
+- [ ] New feature (non-breaking change that adds functionality)
+- [ ] Breaking change (fix or feature that would cause existing functionality to not work as expected)
+- [ ] Documentation update
+- [ ] Refactoring (no functional changes)
+- [ ] Test improvements
+
+## Checklist
+
+- [ ] My code follows MCPKernel's [coding conventions](CONTRIBUTING.md)
+- [ ] I have added tests that prove my fix/feature works
+- [ ] All tests pass: `python -m pytest tests/ -v --tb=short`
+- [ ] Linting passes: `ruff check src/ tests/`
+- [ ] I have updated documentation (if applicable)
+- [ ] I have used conventional commit messages (`feat:`, `fix:`, `docs:`, etc.)
+- [ ] My changes don't introduce security vulnerabilities
+
+## Test Results
+
+<!-- Paste output of `python -m pytest tests/ -v --tb=short` -->
+
+```
+```

mcpkernel-0.1.0/.github/copilot-instructions.md

@@ -0,0 +1,89 @@
+# MCPKernel — Project Context for All Agents
+
+## Project Overview
+MCPKernel is an open-source **Execution Sovereignty Stack** — a mandatory, deterministic MCP/A2A gateway that makes every agent tool call provably replayable, taint-safe, and policy-enforced. Licensed under Apache 2.0.
+
+**Repository**: `piyushptiwari1/mcpkernel`
+
+## Architecture
+- **11 packages** in `src/mcpkernel/`: proxy, sandbox, dee, taint, context, ebpf, policy, audit, observability, cli, agent_manifest
+- **Proxy**: AsyncIO MCP/A2A transparent gateway with SSE/stdio transport
+- **Policy**: YAML-based rules engine with OWASP ASI 2026 mappings
+- **Taint**: Multi-mode taint tracking (FULL/LIGHT/OFF) for secrets, PII, user input
+- **Sandbox**: Docker, Firecracker, WASM, Microsandbox backends
+- **DEE**: Deterministic Execution Envelopes — hashed, Sigstore-signed, replayable
+- **Audit**: Tamper-proof append-only logs with SIEM export (CEF, JSONL, CSV)
+- **Context**: Environment snapshots and drift detection
+- **Observability**: OpenTelemetry metrics and Prometheus export
+- **eBPF**: Kernel-level syscall filtering
+- **Agent Manifest**: agent.yaml loader, policy bridge, tool validator, proxy hook
+
+## Code Standards
+- Python >=3.12 (tested on 3.12 and 3.13, developed on 3.13.12)
+- Async-first using `asyncio`
+- Type hints on all public APIs
+- Tests in `tests/` using `pytest` with async support
+- All 443 tests must pass before merging to main
+- Coverage must be ≥80% (`python -m pytest --cov=mcpkernel`)
+- Lint clean: `ruff check src/ tests/` must show zero errors
+- Format clean: `ruff format --check src/ tests/` must pass
+
+## Build & Test
+```bash
+# Install (using uv)
+uv venv --python 3.13
+source .venv/bin/activate
+uv pip install -e ".[dev]"
+
+# Run all tests
+python -m pytest tests/ -v --tb=short
+
+# Run specific test module
+python -m pytest tests/test_proxy.py -v
+
+# Lint + Format
+ruff check src/ tests/
+ruff format --check src/ tests/
+
+# Type check
+mypy src/mcpkernel/
+```
+
+## Git Workflow
+- `main` branch: stable, all tests passing
+- `development` branch: active work, may have failing tests
+- Feature branches: `feature/<description>` off development
+- Bug fix branches: `fix/<description>` off development
+- Always run tests before merging to main
+- Use conventional commits: `feat:`, `fix:`, `docs:`, `test:`, `refactor:`, `chore:`
+
+## Key Files
+- `README.md` — Project overview and quick start
+- `docs/USAGE.md` — Detailed usage guide
+- `CHANGELOG.md` — Version history
+- `CONTRIBUTING.md` — Contribution guidelines
+- `pyproject.toml` — Project metadata and dependencies
+- `policies/` — Example YAML policy files
+- `src/mcpkernel/agent_manifest/` — Agent manifest loader, policy bridge, tool validator, hooks
+
+## Agent Team Guidelines
+- When making changes, always run `python -m pytest tests/ -v --tb=short` to validate
+- When fixing issues, create a test that reproduces the bug first
+- When adding features, add corresponding tests
+- Update `README.md` and `docs/USAGE.md` when public APIs change
+- Track all work through GitHub Issues with appropriate labels
+
+## Agent System Overview (16 agents — internal tooling only, not shipped)
+- **Control**: team-lead (orchestrator), planner (spec writer)
+- **Intelligence**: issue-hunter (external + internal structural scan), repo-scout, researcher, use-case-scout, contributor-booster
+- **Execution**: code-improver, test-writer, test-runner
+- **Quality**: code-quality-agent (lint, type check, format, coverage, compatibility — NEW Sprint 2)
+- **Validation**: security-agent (hard gate), reviewer (hard gate)
+- **Support**: docs-updater, branch-manager (PR-only, never merges to main)
+- **Meta**: agent-architect (proposal-only, read-only — now detects quality blind spots)
+- Execution chain: `code-improver → test-writer → test-runner → code-quality-agent → security-agent → reviewer → docs-updater → branch-manager`
+- Destructive operations (file/function deletion) emit `⚠️ DESTRUCTIVE` tag and halt pipeline for human review
+- `pyproject.toml` auto-grant exception: if test-runner fails with `ModuleNotFoundError`, code-improver may add the missing dependency without human gate
+- Sequence lock: docs-updater always finishes before contributor-booster touches README.md
+- Agent definitions live in `.github/agents/` (gitignored)
+- Project board at `.agent-workspace/board.json` (gitignored)

mcpkernel-0.1.0/.github/instructions/policy-writing.instructions.md

@@ -0,0 +1,27 @@
+---
+description: "Use when working with MCPKernel YAML policy files. Covers policy syntax, rule structure, OWASP ASI mappings, and best practices for writing security policies."
+applyTo: "policies/**/*.yaml"
+---
+
+# MCPKernel Policy Writing Guide
+
+## Policy Structure
+```yaml
+version: "1.0"
+rules:
+  - id: "rule-unique-id"
+    description: "What this rule does"
+    tool: "tool_name"         # or "*" for all tools
+    action: "allow|deny|audit"
+    conditions:
+      - field: "argument_name"
+        operator: "equals|contains|matches|not_contains"
+        value: "match_value"
+    owasp_asi: "ASI-XX"      # Optional OWASP mapping
+```
+
+## Best Practices
+- Use specific tool names over wildcards when possible
+- Always include `description` for audit trail clarity
+- Map rules to OWASP ASI categories for compliance reporting
+- Test policies with: `python -m pytest tests/test_policy.py -v`

mcpkernel-0.1.0/.github/instructions/python-conventions.instructions.md

@@ -0,0 +1,30 @@
+---
+description: "Use when writing or modifying Python code in MCPKernel. Covers async patterns, type hints, structlog logging, error handling, and module conventions."
+applyTo: "src/**/*.py"
+---
+
+# MCPKernel Python Conventions
+
+## Async-First
+- All I/O-bound functions must be `async def`
+- Use `asyncio.gather()` for concurrent operations
+- Never use blocking I/O in async functions (use `aiofiles`, `aiohttp`, etc.)
+
+## Type Hints
+- All public functions and methods must have type annotations
+- Use `from __future__ import annotations` for forward references
+- Use `Optional[X]` not `X | None` (Python 3.10 compatibility)
+
+## Logging
+- Use `structlog` — NOT stdlib `logging`
+- Get logger: `logger = structlog.get_logger(__name__)`
+- Include context: `logger.info("action_description", key=value)`
+
+## Error Handling
+- Define custom exceptions per package in `exceptions.py`
+- Catch specific exceptions, not broad `Exception`
+- For async retry: use exponential backoff with jitter
+
+## Imports
+- stdlib → third-party → local (separated by blank lines)
+- Use absolute imports: `from mcpkernel.policy.engine import PolicyEngine`

mcpkernel-0.1.0/.github/instructions/testing-guidelines.instructions.md

@@ -0,0 +1,55 @@
+---
+description: "Use when writing or modifying tests for MCPKernel. Covers pytest patterns, async testing, fixtures, and test structure."
+applyTo: "tests/**/*.py"
+---
+
+# MCPKernel Testing Guidelines
+
+## Framework
+- pytest with `pytest-asyncio` for async tests
+- Mark async tests: `@pytest.mark.asyncio`
+- Shared fixtures in `tests/conftest.py`
+
+## Test Structure
+```python
+class TestFeatureName:
+    """Tests for feature_name."""
+    
+    def test_expected_behavior(self):
+        """Test that X does Y when Z."""
+        # Arrange
+        ...
+        # Act
+        result = function_under_test(...)
+        # Assert
+        assert result == expected
+    
+    @pytest.mark.asyncio
+    async def test_async_behavior(self):
+        """Test async operation."""
+        result = await async_function(...)
+        assert result is not None
+```
+
+## Naming
+- Files: `test_<module>.py`
+- Classes: `TestClassName`
+- Functions: `test_<behavior>_<condition>`
+
+## Commands
+```bash
+# All tests
+python -m pytest tests/ -v --tb=short
+
+# Single file
+python -m pytest tests/test_proxy.py -v
+
+# Single test
+python -m pytest tests/test_proxy.py::TestProxy::test_name -v
+```
+
+## Rules
+- Tests must not depend on external services
+- Use mocks for I/O — `unittest.mock.AsyncMock` for async
+- Each test must be independent and idempotent
+- Target: all 106+ existing tests must continue to pass

mcpkernel-0.1.0/.github/skills/docs-sync/SKILL.md

@@ -0,0 +1,57 @@
+---
+name: docs-sync
+description: 'Multi-step workflow to audit MCPKernel documentation against the codebase and update README.md, docs/USAGE.md, CHANGELOG.md. Use when synchronizing documentation with code changes, auditing doc accuracy, or before releases.'
+---
+
+# Documentation Sync Workflow
+
+## When to Use
+- After a batch of code changes to sync docs
+- Before preparing a release
+- When public APIs have changed
+- Regular documentation audits
+
+## Procedure
+
+### Step 1: Audit README.md
+1. Read `README.md`
+2. Verify:
+   - Python version badge matches `pyproject.toml`
+   - Quick start commands work
+   - Feature list matches actual packages in `src/mcpkernel/`
+   - Architecture diagram is accurate
+   - All links are valid
+
+### Step 2: Audit docs/USAGE.md
+1. Read `docs/USAGE.md`
+2. Cross-reference with:
+   - `src/mcpkernel/config.py` for configuration options
+   - `src/mcpkernel/cli.py` for CLI commands
+   - `src/mcpkernel/policy/` for policy syntax
+   - `policies/` for example policies
+3. Verify all code examples match current API
+
+### Step 3: Update CHANGELOG.md
+1. Check git log for unreleased changes:
+   ```bash
+   git log --oneline --since="last tag" 
+   ```
+2. Categorize changes: Added, Changed, Fixed, Security
+3. Add entries under `[Unreleased]` section
+
+### Step 4: Update CONTRIBUTING.md
+1. Verify build/test commands are current
+2. Check that development workflow matches actual practice
+
+### Step 5: Apply Updates
+- Edit files with accurate, verified information
+- Keep style consistent with existing docs
+- Don't add fictional features
+
+## References
+- `README.md` — Project overview
+- `docs/USAGE.md` — Usage guide
+- `CHANGELOG.md` — Version history
+- `CONTRIBUTING.md` — Contributor guide
+- `src/mcpkernel/config.py` — Configuration reference
+- `src/mcpkernel/cli.py` — CLI reference

mcpkernel-0.1.0/.github/skills/research-and-improve/SKILL.md

@@ -0,0 +1,53 @@
+---
+name: research-and-improve
+description: 'Multi-step workflow to research latest MCP security techniques, async Python patterns, sandboxing approaches, and implement improvements to MCPKernel. Use when upgrading architecture, adding new security features, or optimizing performance based on latest research.'
+---
+
+# Research and Improve Workflow
+
+## When to Use
+- Discovering and implementing latest security techniques
+- Optimizing performance based on current best practices
+- Upgrading protocol support (MCP, A2A)
+- Adding new sandboxing or taint tracking capabilities
+
+## Procedure
+
+### Step 1: Research
+1. Search for latest MCP protocol specification updates
+2. Research current security approaches for:
+   - Taint analysis and information flow control
+   - Container sandboxing advancements
+   - eBPF security monitoring
+   - Policy engine improvements
+3. Look for Python async optimization techniques
+4. Check for new OWASP ASI guidelines
+
+### Step 2: Evaluate Applicability
+1. Read current MCPKernel implementation in `src/mcpkernel/`
+2. Compare with researched techniques
+3. Identify improvements that:
+   - Fit MCPKernel's async Python architecture
+   - Don't break existing APIs
+   - Have measurable impact
+
+### Step 3: Implement
+1. Create a feature branch: `feature/<improvement-name>`
+2. Write tests first for the new behavior
+3. Implement the improvement with minimal changes
+4. Run full test suite: `python -m pytest tests/ -v --tb=short`
+
+### Step 4: Document
+1. Update `docs/USAGE.md` if usage changes
+2. Update `CHANGELOG.md` with the improvement
+3. Update `README.md` if it's a notable feature
+
+### Step 5: Report
+Return research findings, what was implemented, and validation results.
+
+## References
+- MCPKernel architecture: `src/mcpkernel/`
+- Configuration: `src/mcpkernel/config.py`
+- Proxy layer: `src/mcpkernel/proxy/`
+- Policy engine: `src/mcpkernel/policy/`
+- Taint tracking: `src/mcpkernel/taint/`

mcpkernel-0.1.0/.github/skills/search-and-fix/SKILL.md

@@ -0,0 +1,42 @@
+---
+name: search-and-fix
+description: 'Multi-step workflow to discover issues in MCPKernel and similar repos, implement fixes, and validate with tests. Use when finding and fixing bugs, addressing security gaps, or implementing improvements discovered from issue analysis.'
+---
+
+# Search and Fix Workflow
+
+## When to Use
+- Finding and fixing bugs from GitHub issues
+- Addressing security vulnerabilities discovered in similar projects
+- Implementing improvements from issue analysis
+
+## Procedure
+
+### Step 1: Discover Issues
+1. Use web search to find open issues in `piyushptiwari1/mcpkernel`
+2. Search similar MCP/security projects for resolved issues that may affect MCPKernel
+3. Analyze the codebase with `search` for patterns matching known bugs
+
+### Step 2: Triage and Plan
+1. Prioritize findings: Critical > High > Medium > Low
+2. For each issue, identify the affected files in `src/mcpkernel/`
+3. Create a brief implementation plan
+
+### Step 3: Implement Fix
+1. Read the target source files to understand current behavior
+2. Write a failing test in `tests/` that reproduces the issue
+3. Implement the minimal fix in `src/mcpkernel/`
+4. Run: `python -m pytest tests/ -v --tb=short`
+
+### Step 4: Validate
+1. Ensure all 106+ tests pass (including the new one)
+2. Run `ruff check src/ tests/` for lint compliance
+3. Document the change for the changelog
+
+### Step 5: Report
+Return a summary of what was found, fixed, and validated.
+
+## References
+- MCPKernel source: `src/mcpkernel/`
+- Tests: `tests/`
+- Policies: `policies/`

mcpkernel-0.1.0/.github/skills/test-and-merge/SKILL.md

@@ -0,0 +1,64 @@
+---
+name: test-and-merge
+description: 'Multi-step workflow to run the full MCPKernel test suite, validate code quality, and merge development branch to main when all checks pass. Use when validating changes, preparing for merge, or checking if development is ready for main.'
+---
+
+# Test and Merge Workflow
+
+## When to Use
+- Validating that all tests pass before merging
+- Preparing the development branch for merge to main
+- Running comprehensive quality checks
+
+## Procedure
+
+### Step 1: Verify Branch State
+```bash
+git branch
+git status
+git log --oneline development..HEAD  # or HEAD..development
+```
+
+### Step 2: Run Full Test Suite
+```bash
+python -m pytest tests/ -v --tb=short
+```
+- All 106+ tests must pass
+- Zero failures, zero errors
+
+### Step 3: Run Lint Check
+```bash
+ruff check src/ tests/
+```
+- No lint errors allowed
+
+### Step 4: Verify Documentation
+1. Check `CHANGELOG.md` has entries for recent changes
+2. Check `README.md` is current
+3. Check `docs/USAGE.md` matches current APIs
+
+### Step 5: Merge Decision
+If ALL checks pass:
+```bash
+git checkout main
+git merge --no-ff development -m "chore: merge development to main — all tests passing"
+git checkout development
+```
+
+If ANY check fails:
+- Report failures with details
+- Do NOT merge
+- List what needs to be fixed
+
+### Step 6: Report
+```
+## Merge Report
+- Tests: PASS/FAIL (count)
+- Lint: PASS/FAIL
+- Docs: UP TO DATE / NEEDS UPDATE
+- Merge: COMPLETED / BLOCKED (reason)
+```
+
+## References
+- Test suite: `tests/`
+- CI config: `.github/workflows/ci.yml`