vamsi-purecipher commited on
Commit
7e905d6
·
verified ·
1 Parent(s): b0c52ab

Deploy tested PureCipher build 5bd407c3b7812ee3596ef0e1eea9afa5ecff0534

Browse files
.cursor/rules/core-mcp-objects.mdc DELETED
@@ -1,13 +0,0 @@
1
- ---
2
- description:
3
- globs:
4
- alwaysApply: true
5
- ---
6
- There are four major MCP object types:
7
-
8
- - Tools (src/tools/)
9
- - Resources (src/resources/)
10
- - Resource Templates (src/resources/)
11
- - Prompts (src/prompts)
12
-
13
- While these have slightly different semantics and implementations, in general changes that affect interactions with any one (like adding tags, importing, etc.) will need to be adopted, applied, and tested on all others. Be sure to look at not only the object definition but also the related `Manager` (e.g. `ToolManager`, `ResourceManager`, and `PromptManager`). Also note that while resources and resource templates are different objects, they both are handled by the `ResourceManager`.
 
 
 
 
 
 
 
 
 
 
 
 
 
 
.gitattributes CHANGED
@@ -9,3 +9,5 @@ wheels/fastmcp-0.0.1.dev4087+67f290ef-py3-none-any.whl filter=lfs diff=lfs merge
9
  wheels/fastmcp_slim-0.0.1.dev4087+67f290ef-py3-none-any.whl filter=lfs diff=lfs merge=lfs -text
10
  wheels/fastmcp-0.0.1.dev4088+b8f75f12-py3-none-any.whl filter=lfs diff=lfs merge=lfs -text
11
  wheels/fastmcp_slim-0.0.1.dev4088+b8f75f12-py3-none-any.whl filter=lfs diff=lfs merge=lfs -text
 
 
 
9
  wheels/fastmcp_slim-0.0.1.dev4087+67f290ef-py3-none-any.whl filter=lfs diff=lfs merge=lfs -text
10
  wheels/fastmcp-0.0.1.dev4088+b8f75f12-py3-none-any.whl filter=lfs diff=lfs merge=lfs -text
11
  wheels/fastmcp_slim-0.0.1.dev4088+b8f75f12-py3-none-any.whl filter=lfs diff=lfs merge=lfs -text
12
+ wheels/fastmcp-0.0.1.dev4090+5bd407c3-py3-none-any.whl filter=lfs diff=lfs merge=lfs -text
13
+ wheels/fastmcp_slim-0.0.1.dev4090+5bd407c3-py3-none-any.whl filter=lfs diff=lfs merge=lfs -text
.github/copilot-instructions.md DELETED
@@ -1 +0,0 @@
1
- ../AGENTS.md
 
 
AGENTS.md DELETED
@@ -1,251 +0,0 @@
1
- # FastMCP Development Guidelines
2
-
3
- > **Audience**: LLM-driven engineering agents and human developers
4
-
5
- FastMCP is a comprehensive Python framework (Python ≥3.10) for building Model Context Protocol (MCP) servers and clients. This is the actively maintained v2.0 providing a complete toolkit for the MCP ecosystem.
6
-
7
- ## Required Development Workflow
8
-
9
- **CRITICAL**: Always run these commands in sequence before committing:
10
-
11
- ```bash
12
- uv sync # Install dependencies
13
- uv run pre-commit run --all-files # Ruff + Prettier + ty
14
- uv run pytest # Run full test suite
15
- ```
16
-
17
- **All three must pass** - this is enforced by CI. Alternative: `just build && just typecheck && just test`
18
-
19
- **Tests must pass and lint/typing must be clean before committing.**
20
-
21
- ## Repository Structure
22
-
23
- | Path | Purpose |
24
- | ---------------- | ------------------------------------------------------ |
25
- | `src/fastmcp/` | Library source code (Python ≥ 3.10) |
26
- | `├─server/` | Server implementation, `FastMCP`, auth, networking |
27
- | `│ ├─auth/` | Authentication providers (Bearer, JWT, WorkOS) |
28
- | `│ └─middleware/` | Error handling, logging, rate limiting |
29
- | `├─client/` | High-level client SDK + transports |
30
- | `│ └─auth/` | Client authentication (Bearer, OAuth) |
31
- | `├─tools/` | Tool implementations + `ToolManager` |
32
- | `├─resources/` | Resources, templates + `ResourceManager` |
33
- | `├─prompts/` | Prompt templates + `PromptManager` |
34
- | `├─cli/` | FastMCP CLI commands (`run`, `dev`, `install`) |
35
- | `├─contrib/` | Community contributions (bulk caller, mixins) |
36
- | `├─experimental/` | Experimental features (new OpenAPI parser) |
37
- | `└─utilities/` | Shared utilities (logging, JSON schema, HTTP) |
38
- | `tests/` | Comprehensive pytest suite with markers |
39
- | `docs/` | Mintlify documentation (published to gofastmcp.com) |
40
- | `examples/` | Runnable demo servers (echo, smart_home, atproto) |
41
-
42
- ## Core MCP Objects
43
-
44
- When modifying MCP functionality, changes typically need to be applied across all object types:
45
-
46
- - **Tools** (`src/tools/` + `ToolManager`)
47
- - **Resources** (`src/resources/` + `ResourceManager`)
48
- - **Resource Templates** (`src/resources/` + `ResourceManager`)
49
- - **Prompts** (`src/prompts/` + `PromptManager`)
50
-
51
- ## Testing Best Practices
52
-
53
- ### Testing Standards
54
-
55
- - Every test: atomic, self-contained, single functionality
56
- - Use parameterization for multiple examples of same functionality
57
- - Use separate tests for different functionality pieces
58
- - Put imports at the top of the file, not in the test body
59
- - **NEVER** add `@pytest.mark.asyncio` to tests - `asyncio_mode = "auto"` is set globally
60
- - **ALWAYS** run pytest after significant changes
61
-
62
- ### Always Use In-Memory Transport
63
-
64
- Pass FastMCP servers directly to clients for testing:
65
-
66
- ```python
67
- mcp = FastMCP("TestServer")
68
-
69
- @mcp.tool
70
- def greet(name: str) -> str:
71
- return f"Hello, {name}!"
72
-
73
- # Direct connection - no network complexity
74
- async with Client(mcp) as client:
75
- result = await client.call_tool("greet", {"name": "World"})
76
- ```
77
-
78
- Only use HTTP transport when explicitly testing network features:
79
-
80
- ```python
81
- # Network testing only
82
- async with Client(transport=StreamableHttpTransport(server_url)) as client:
83
- result = await client.ping()
84
- ```
85
-
86
- ## Development Rules
87
-
88
- ### Git & CI
89
-
90
- - Pre-commit hooks are required (run automatically on commits)
91
- - Never amend commits to fix pre-commit failures
92
- - Apply PR labels: bugs/breaking/enhancements/features
93
- - Improvements = enhancements (not features) unless specified
94
- - **NEVER** force-push on collaborative repos
95
- - **ALWAYS** run pre-commit before PRs
96
-
97
- ### Commit Messages and Agent Attribution
98
-
99
- - **Agents NOT acting on behalf of @jlowin MUST identify themselves** (e.g., "🤖 Generated with Claude Code" in commits/PRs)
100
- - Keep commit messages brief - ideally just headlines, not detailed messages
101
- - Focus on what changed, not how or why
102
- - Always read issue comments for follow-up information (treat maintainers as authoritative)
103
-
104
- ### PR Messages - Required Structure
105
-
106
- - 1-2 paragraphs: problem/tension + solution (PRs are documentation!)
107
- - Focused code example showing key capability
108
- - **Avoid:** bullet summaries, exhaustive change lists, verbose closes/fixes, marketing language
109
- - **Do:** Be opinionated about why change matters, show before/after scenarios
110
- - Minor fixes: keep body short and concise
111
- - No "test plan" sections or testing summaries
112
-
113
- ### Code Standards
114
-
115
- - Python ≥ 3.10 with full type annotations
116
- - Follow existing patterns and maintain consistency
117
- - **Prioritize readable, understandable code** - clarity over cleverness
118
- - Avoid obfuscated or confusing patterns even if they're shorter
119
- - Use `# type: ignore[attr-defined]` in tests for MCP results instead of type assertions
120
- - Each feature needs corresponding tests
121
-
122
- ### Documentation
123
-
124
- - Uses Mintlify framework
125
- - Files must be in docs.json to be included
126
- - Never modify `docs/python-sdk/**` (auto-generated)
127
- - **Core Principle:** A feature doesn't exist unless it is documented!
128
-
129
- ### Documentation Guidelines
130
-
131
- - **Code Examples:** Explain before showing code, make blocks fully runnable (include imports)
132
- - **Structure:** Headers form navigation guide, logical H2/H3 hierarchy
133
- - **Content:** User-focused sections, motivate features (why) before mechanics (how)
134
- - **Style:** Prose over code comments for important information
135
-
136
- ## Code Review Guidelines
137
-
138
- ### Philosophy
139
-
140
- Code review is about maintaining a healthy codebase while helping contributors succeed. The burden of proof is on the PR to demonstrate it adds value in the intended way. Your job is to help it get there through actionable feedback.
141
-
142
- **Critical**: A perfectly written PR that adds unwanted functionality must still be rejected. The code must advance the codebase in the intended direction, not just be well-written. When rejecting, provide clear guidance on how to align with project goals.
143
-
144
- Be friendly and welcoming while maintaining high standards. Call out what works well - this reinforces good patterns. When code needs improvement, be specific about why and how to fix it. Remember that PRs serve as documentation for future developers.
145
-
146
- ### Focus On
147
-
148
- - **Does this advance the codebase in the intended direction?** (Even perfect code for unwanted features should be rejected)
149
- - **API design and naming clarity** - Identify confusing patterns (e.g., parameter values that contradict defaults) or non-idiomatic code (mutable defaults, etc.). Contributed code will need to be maintained indefinitely, and by someone other than the author (unless the author is a maintainer).
150
- - **Suggest specific improvements**, not generic "add more tests" comments
151
- - **Think about API ergonomics and learning curve** from a user perspective
152
-
153
- ### For Agent Reviewers
154
-
155
- - **Read the full context**: Always examine related files, tests, and documentation before reviewing
156
- - **Check against established patterns**: Look for consistency with existing codebase conventions
157
- - **Verify functionality claims**: Don't just read code - understand what it actually does
158
- - **Consider edge cases**: Think through error conditions and boundary scenarios
159
-
160
- ### Avoid
161
-
162
- - Generic feedback without specifics
163
- - Hypothetical problems unlikely to occur
164
- - Nitpicking organizational choices without strong reason
165
- - Summarizing what the PR already describes
166
- - Star ratings or excessive emojis
167
- - Bikeshedding style preferences when functionality is correct
168
- - Requesting changes without suggesting solutions
169
- - Focusing on personal coding style over project conventions
170
-
171
- ### Tone
172
-
173
- - Acknowledge good decisions ("This API design is clean")
174
- - Be direct but respectful
175
- - Explain impact ("This will confuse users because...")
176
- - Remember: Someone else maintains this code forever
177
-
178
- ### Decision Framework
179
-
180
- Before approving, ask yourself:
181
-
182
- 1. Does this PR achieve its stated purpose?
183
- 2. Is that purpose aligned with where the codebase should go?
184
- 3. Would I be comfortable maintaining this code?
185
- 4. Have I actually understood what it does, not just what it claims?
186
- 5. Does this change introduce technical debt?
187
-
188
- If something needs work, your review should help it get there through specific, actionable feedback. If it's solving the wrong problem, say so clearly.
189
-
190
- ### Review Comment Examples
191
-
192
- **Good Review Comments:**
193
-
194
- ❌ "Add more tests"
195
- ✅ "The `handle_timeout` method needs tests for the edge case where timeout=0"
196
-
197
- ❌ "This API is confusing"
198
- ✅ "The parameter name `data` is ambiguous - consider `message_content` to match the MCP specification"
199
-
200
- ❌ "This could be better"
201
- ✅ "This approach works but creates a circular dependency. Consider moving the validation to `utils/validators.py`"
202
-
203
- ### Review Checklist
204
-
205
- Before approving, verify:
206
- - [ ] All required development workflow steps completed (uv sync, pre-commit, pytest)
207
- - [ ] Changes align with repository patterns and conventions
208
- - [ ] API changes are documented and backwards-compatible where possible
209
- - [ ] Error handling follows project patterns (specific exception types)
210
- - [ ] Tests cover new functionality and edge cases
211
-
212
- ## Key Tools & Commands
213
-
214
- ### Environment Setup
215
-
216
- ```bash
217
- git clone <repo>
218
- cd fastmcp
219
- uv sync # Installs all deps including dev tools
220
- ```
221
-
222
- ### Validation Commands (Run Frequently)
223
-
224
- - **Linting**: `uv run ruff check` (or with `--fix`)
225
- - **Type Checking**: `uv run ty check`
226
- - **All Checks**: `uv run pre-commit run --all-files`
227
-
228
- ### Testing
229
-
230
- - **Standard**: `uv run pytest`
231
- - **Integration**: `uv run pytest -m "integration"`
232
- - **Excluding markers**: `uv run pytest -m "not integration and not client_process"`
233
-
234
- ### CLI Usage
235
-
236
- - **Run server**: `uv run fastmcp run server.py`
237
- - **Inspect server**: `uv run fastmcp inspect server.py`
238
-
239
- ## Critical Patterns
240
-
241
- ### Error Handling
242
-
243
- - Never use bare `except` - be specific with exception types
244
- - Use `# type: ignore[attr-defined]` in tests for MCP results
245
-
246
- ### Build Issues (Common Solutions)
247
-
248
- 1. **Dependencies**: Always `uv sync` first
249
- 2. **Pre-commit fails**: Run `uv run pre-commit run --all-files` to see failures
250
- 3. **Type errors**: Use `uv run ty check` directly, check `pyproject.toml` config
251
- 4. **Test timeouts**: Default 3s - optimize or mark as integration tests
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
CLAUDE.md DELETED
@@ -1 +0,0 @@
1
- AGENTS.md
 
 
CODE_OF_CONDUCT.md DELETED
@@ -1,128 +0,0 @@
1
- # Contributor Covenant Code of Conduct
2
-
3
- ## Our Pledge
4
-
5
- We as members, contributors, and leaders pledge to make participation in our
6
- community a harassment-free experience for everyone, regardless of age, body
7
- size, visible or invisible disability, ethnicity, sex characteristics, gender
8
- identity and expression, level of experience, education, socio-economic status,
9
- nationality, personal appearance, race, religion, or sexual identity
10
- and orientation.
11
-
12
- We pledge to act and interact in ways that contribute to an open, welcoming,
13
- diverse, inclusive, and healthy community.
14
-
15
- ## Our Standards
16
-
17
- Examples of behavior that contributes to a positive environment for our
18
- community include:
19
-
20
- * Demonstrating empathy and kindness toward other people
21
- * Being respectful of differing opinions, viewpoints, and experiences
22
- * Giving and gracefully accepting constructive feedback
23
- * Accepting responsibility and apologizing to those affected by our mistakes,
24
- and learning from the experience
25
- * Focusing on what is best not just for us as individuals, but for the
26
- overall community
27
-
28
- Examples of unacceptable behavior include:
29
-
30
- * The use of sexualized language or imagery, and sexual attention or
31
- advances of any kind
32
- * Trolling, insulting or derogatory comments, and personal or political attacks
33
- * Public or private harassment
34
- * Publishing others' private information, such as a physical or email
35
- address, without their explicit permission
36
- * Other conduct which could reasonably be considered inappropriate in a
37
- professional setting
38
-
39
- ## Enforcement Responsibilities
40
-
41
- Community leaders are responsible for clarifying and enforcing our standards of
42
- acceptable behavior and will take appropriate and fair corrective action in
43
- response to any behavior that they deem inappropriate, threatening, offensive,
44
- or harmful.
45
-
46
- Community leaders have the right and responsibility to remove, edit, or reject
47
- comments, commits, code, wiki edits, issues, and other contributions that are
48
- not aligned to this Code of Conduct, and will communicate reasons for moderation
49
- decisions when appropriate.
50
-
51
- ## Scope
52
-
53
- This Code of Conduct applies within all community spaces, and also applies when
54
- an individual is officially representing the community in public spaces.
55
- Examples of representing our community include using an official e-mail address,
56
- posting via an official social media account, or acting as an appointed
57
- representative at an online or offline event.
58
-
59
- ## Enforcement
60
-
61
- Instances of abusive, harassing, or otherwise unacceptable behavior may be
62
- reported to the community leaders responsible for enforcement at
63
- chris@prefect.io.
64
- All complaints will be reviewed and investigated promptly and fairly.
65
-
66
- All community leaders are obligated to respect the privacy and security of the
67
- reporter of any incident.
68
-
69
- ## Enforcement Guidelines
70
-
71
- Community leaders will follow these Community Impact Guidelines in determining
72
- the consequences for any action they deem in violation of this Code of Conduct:
73
-
74
- ### 1. Correction
75
-
76
- **Community Impact**: Use of inappropriate language or other behavior deemed
77
- unprofessional or unwelcome in the community.
78
-
79
- **Consequence**: A private, written warning from community leaders, providing
80
- clarity around the nature of the violation and an explanation of why the
81
- behavior was inappropriate. A public apology may be requested.
82
-
83
- ### 2. Warning
84
-
85
- **Community Impact**: A violation through a single incident or series
86
- of actions.
87
-
88
- **Consequence**: A warning with consequences for continued behavior. No
89
- interaction with the people involved, including unsolicited interaction with
90
- those enforcing the Code of Conduct, for a specified period of time. This
91
- includes avoiding interactions in community spaces as well as external channels
92
- like social media. Violating these terms may lead to a temporary or
93
- permanent ban.
94
-
95
- ### 3. Temporary Ban
96
-
97
- **Community Impact**: A serious violation of community standards, including
98
- sustained inappropriate behavior.
99
-
100
- **Consequence**: A temporary ban from any sort of interaction or public
101
- communication with the community for a specified period of time. No public or
102
- private interaction with the people involved, including unsolicited interaction
103
- with those enforcing the Code of Conduct, is allowed during this period.
104
- Violating these terms may lead to a permanent ban.
105
-
106
- ### 4. Permanent Ban
107
-
108
- **Community Impact**: Demonstrating a pattern of violation of community
109
- standards, including sustained inappropriate behavior, harassment of an
110
- individual, or aggression toward or disparagement of classes of individuals.
111
-
112
- **Consequence**: A permanent ban from any sort of public interaction within
113
- the community.
114
-
115
- ## Attribution
116
-
117
- This Code of Conduct is adapted from the [Contributor Covenant][homepage],
118
- version 2.0, available at
119
- https://www.contributor-covenant.org/version/2/0/code_of_conduct.html.
120
-
121
- Community Impact Guidelines were inspired by [Mozilla's code of conduct
122
- enforcement ladder](https://github.com/mozilla/diversity).
123
-
124
- [homepage]: https://www.contributor-covenant.org
125
-
126
- For answers to common questions about this code of conduct, see the FAQ at
127
- https://www.contributor-covenant.org/faq. Translations are available at
128
- https://www.contributor-covenant.org/translations.
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
README.md CHANGED
@@ -43,7 +43,7 @@ For example, consider an assistant working with customer records: MCP carries th
43
  1. **Try the backend:** use the health request below to inspect this Space. It is the registry service, not a general-purpose agent or the calculator example.
44
  2. **Build a server:** install the matching fork packages, define your tools, and configure `SecurityConfig` for the controls your application needs.
45
  3. **Connect a client:** point an MCP client at your server’s endpoint. The [server-and-client quickstart](https://github.com/PureCipher/xsecuremcp2.0#build-an-mcp-server) demonstrates a tool call and receipt verification.
46
- 4. **Check enforcement:** follow the [worked usage guide](https://github.com/PureCipher/xsecuremcp2.0/blob/main/docs/using-xsecuremcp.md) to allow one operation, deny another, and understand the resulting evidence.
47
  5. **Share and operate:** use PureCipher Publisher to submit projects to your chosen registry, and the separate xregistry console to manage it. Configure authentication, moderation, and persistent storage for your deployment.
48
 
49
  ## What this Space runs
@@ -96,8 +96,8 @@ The container runs as user 1000 and listens on port 8000. It installs the tested
96
 
97
  | Field | Value |
98
  | --- | --- |
99
- | GitHub source | [`b8f75f12f0f1`](https://github.com/PureCipher/xsecuremcp2.0/commit/b8f75f12f0f1f7331917a7785111bd3b1ffd4a06) |
100
- | Package version | `0.0.1.dev4088+b8f75f12` |
101
  | Build metadata | [`build.json`](https://huggingface.co/spaces/purecipher/xsecuremcp/blob/main/build.json) |
102
 
103
  Pushes to the GitHub repository’s `main` branch trigger tests, static checks, clean wheel installation checks, and Docker health checks before publication. Successful builds update this Space and replace its current wheel files. Hub history is retained.
 
43
  1. **Try the backend:** use the health request below to inspect this Space. It is the registry service, not a general-purpose agent or the calculator example.
44
  2. **Build a server:** install the matching fork packages, define your tools, and configure `SecurityConfig` for the controls your application needs.
45
  3. **Connect a client:** point an MCP client at your server’s endpoint. The [server-and-client quickstart](https://github.com/PureCipher/xsecuremcp2.0#build-an-mcp-server) demonstrates a tool call and receipt verification.
46
+ 4. **Check enforcement:** allow one operation, deny another, and inspect the resulting evidence. See the [project README](https://github.com/PureCipher/xsecuremcp2.0#readme) for the security configuration and its boundaries.
47
  5. **Share and operate:** use PureCipher Publisher to submit projects to your chosen registry, and the separate xregistry console to manage it. Configure authentication, moderation, and persistent storage for your deployment.
48
 
49
  ## What this Space runs
 
96
 
97
  | Field | Value |
98
  | --- | --- |
99
+ | GitHub source | [`5bd407c3b781`](https://github.com/PureCipher/xsecuremcp2.0/commit/5bd407c3b7812ee3596ef0e1eea9afa5ecff0534) |
100
+ | Package version | `0.0.1.dev4090+5bd407c3` |
101
  | Build metadata | [`build.json`](https://huggingface.co/spaces/purecipher/xsecuremcp/blob/main/build.json) |
102
 
103
  Pushes to the GitHub repository’s `main` branch trigger tests, static checks, clean wheel installation checks, and Docker health checks before publication. Successful builds update this Space and replace its current wheel files. Hub history is retained.
README_OPENAPI.md DELETED
@@ -1,246 +0,0 @@
1
- # FastMCP OpenAPI Integration
2
-
3
- This document explains how FastMCP's OpenAPI integration works, what features are supported, and how to extend it. The OpenAPI functionality is split across two main files:
4
-
5
- - `server/openapi.py` - High-level FastMCP server implementation and MCP component creation
6
- - `utilities/openapi.py` - Low-level OpenAPI parsing and intermediate representation
7
-
8
- ## Architecture Overview
9
-
10
- ```
11
- OpenAPI Spec → Parse → HTTPRoute IR → Create MCP Components → FastMCP Server
12
- ```
13
-
14
- ### 1. Parsing Phase (`utilities/openapi.py`)
15
-
16
- OpenAPI specifications are parsed into an intermediate representation (IR) that normalizes differences between OpenAPI 3.0 and 3.1:
17
-
18
- - **Input**: Raw OpenAPI spec (dict)
19
- - **Output**: List of `HTTPRoute` objects with normalized parameter information
20
- - **Key Classes**:
21
- - `HTTPRoute` - Represents a single operation
22
- - `ParameterInfo` - Represents a parameter with location, style, explode, etc.
23
- - `RequestBodyInfo` - Represents request body information
24
- - `ResponseInfo` - Represents response information
25
-
26
- ### 2. Component Creation Phase (`server/openapi.py`)
27
-
28
- HTTPRoute objects are converted into FastMCP components based on route mapping rules:
29
-
30
- - **Tools** (`OpenAPITool`) - HTTP operations that can be called
31
- - **Resources** (`OpenAPIResource`) - HTTP endpoints that return data
32
- - **Resource Templates** (`OpenAPIResourceTemplate`) - Parameterized resources
33
-
34
- ## Parameter Handling
35
-
36
- FastMCP supports various OpenAPI parameter serialization styles and formats:
37
-
38
- ### Supported Parameter Locations
39
- - `query` - Query string parameters
40
- - `path` - Path parameters
41
- - `header` - HTTP headers
42
- - `cookie` - Cookie parameters (parsed but not used in requests)
43
-
44
- ### Supported Parameter Styles
45
-
46
- #### Query Parameters
47
- - **`form`** (default) - Standard query parameter format
48
- - `explode=true` (default): `?tags=red&tags=blue`
49
- - `explode=false`: `?tags=red,blue`
50
- - **`deepObject`** - Object parameters with bracket notation
51
- - `explode=true`: `?filter[name]=John&filter[age]=30`
52
- - `explode=false`: Falls back to JSON string (non-standard, logs warning)
53
-
54
- #### Path Parameters
55
- - **`simple`** (default) - Comma-separated for arrays: `/users/1,2,3`
56
-
57
- #### Header Parameters
58
- - **`simple`** (default) - Standard header format
59
-
60
- ### Parameter Type Support
61
-
62
- #### Arrays
63
- - String arrays with `explode=true/false`
64
- - Number arrays with `explode=true/false`
65
- - Boolean arrays with `explode=true/false`
66
- - Complex object arrays (basic support, may not handle all cases)
67
-
68
- #### Objects
69
- - Objects with `deepObject` style and `explode=true`
70
- - Objects with other styles fall back to JSON serialization
71
-
72
- #### Primitives
73
- - Strings, numbers, booleans
74
- - Enums
75
- - Default values
76
-
77
- ## Request Body Handling
78
-
79
- ### Supported Content Types
80
- - `application/json` - JSON request bodies
81
-
82
- ### Schema Support
83
- - Object schemas with properties
84
- - Array schemas
85
- - Primitive schemas
86
- - Schema references (`$ref` to local schemas only)
87
- - Required properties
88
- - Default values
89
-
90
- ## Response Handling
91
-
92
- ### Content Type Detection
93
- - `application/json` - Parsed as JSON
94
- - `text/*` - Returned as text
95
- - `application/xml` - Returned as text
96
- - Other types - Returned as binary
97
-
98
- ### Output Schema Generation
99
- - Success response schemas (200, 201, 202, 204)
100
- - Object response wrapping for MCP compliance
101
- - Schema compression (removes unused `$defs`)
102
-
103
- ## Route Mapping
104
-
105
- Routes are mapped to MCP component types using `RouteMap` configurations:
106
-
107
- ```python
108
- RouteMap(
109
- methods=["GET", "POST"], # HTTP methods to match
110
- pattern=r"/api/users/.*", # Regex pattern for path
111
- mcp_type=MCPType.RESOURCE_TEMPLATE, # Target component type
112
- tags={"user"}, # OpenAPI tags to match (AND condition)
113
- mcp_tags={"fastmcp-user"} # Tags to add to created components
114
- )
115
- ```
116
-
117
- ### Default Behavior
118
- - All routes become **Tools** by default
119
- - Use route maps to override specific patterns
120
-
121
- ### Component Types
122
- - `MCPType.TOOL` - Callable operations
123
- - `MCPType.RESOURCE` - Static data endpoints
124
- - `MCPType.RESOURCE_TEMPLATE` - Parameterized data endpoints
125
- - `MCPType.EXCLUDE` - Skip route entirely
126
-
127
- ## Known Limitations & Edge Cases
128
-
129
- ### Parameter Edge Cases
130
- 1. **Parameter Name Collisions** - When path/query parameters have same names as request body properties, non-body parameters get `__location` suffixes
131
- 2. **Complex Array Serialization** - Limited support for arrays containing objects
132
- 3. **Cookie Parameters** - Parsed but not used in requests
133
- 4. **Non-standard Combinations** - e.g., `deepObject` with `explode=false`
134
-
135
- ### Request Body Edge Cases
136
- 1. **Content Type Priority** - Only first available content type is used
137
- 2. **Nested Objects** - Deep nesting may not serialize correctly
138
- 3. **Binary Content** - No support for file uploads or binary data
139
-
140
- ### Response Edge Cases
141
- 1. **Multiple Content Types** - Only JSON-compatible types are used for output schemas
142
- 2. **Error Responses** - Not used for MCP output schema generation
143
- 3. **Response Headers** - Not captured or exposed
144
-
145
- ### Schema Edge Cases
146
- 1. **External References** - `$ref` to external files not supported
147
- 2. **Circular References** - May cause issues in schema processing
148
- 3. **Polymorphism** - `oneOf`/`anyOf`/`allOf` limited support
149
-
150
- ## Debugging Tips
151
-
152
- ### Common Issues
153
- 1. **"Unknown tool/resource"** - Check route mapping configuration
154
- 2. **Parameter not found** - Check for name collisions or incorrect style/explode
155
- 3. **Invalid request format** - Check parameter serialization and content types
156
- 4. **Schema validation errors** - Check for external refs or complex schemas
157
-
158
- ### Debugging Tools
159
- ```python
160
- # Parse routes to inspect intermediate representation
161
- routes = parse_openapi_to_http_routes(openapi_spec)
162
- for route in routes:
163
- print(f"{route.method} {route.path}")
164
- for param in route.parameters:
165
- print(f" {param.name} ({param.location}): style={param.style}, explode={param.explode}")
166
-
167
- # Check component creation
168
- server = FastMCP.from_openapi(openapi_spec, client)
169
- tools = await server.get_tools()
170
- print(f"Created {len(tools)} tools: {list(tools.keys())}")
171
- ```
172
-
173
- ### Logging
174
- - Set `FASTMCP_LOG_LEVEL=DEBUG` to see detailed parameter processing
175
- - Look for warnings about non-standard parameter combinations
176
- - Check for schema parsing errors in logs
177
-
178
- ## Extension Points
179
-
180
- ### Adding New Parameter Styles
181
- 1. Add style handling in `utilities/openapi.py` - `ParameterInfo` class
182
- 2. Implement serialization logic in `server/openapi.py` - `OpenAPITool.run()`
183
- 3. Add tests for parsing and serialization
184
-
185
- ### Adding New Content Types
186
- 1. Extend request body handling in `OpenAPITool.run()`
187
- 2. Add response parsing logic for new types
188
- 3. Update content type priority in utilities
189
-
190
- ### Custom Route Mapping
191
- Use `route_map_fn` for complex routing logic:
192
-
193
- ```python
194
- def custom_mapper(route: HTTPRoute, current_type: MCPType) -> MCPType:
195
- if route.path.startswith("/admin"):
196
- return MCPType.EXCLUDE
197
- return current_type
198
-
199
- server = FastMCP.from_openapi(spec, client, route_map_fn=custom_mapper)
200
- ```
201
-
202
- ## Testing Patterns
203
-
204
- ### Unit Tests
205
- - Test parameter parsing with various styles/explode combinations
206
- - Test route mapping with different patterns and tags
207
- - Test schema generation and compression
208
-
209
- ### Integration Tests
210
- - Mock HTTP client to verify actual request parameters
211
- - Test end-to-end component creation and execution
212
- - Test error handling and edge cases
213
-
214
- ### Example Test Pattern
215
- ```python
216
- async def test_parameter_style():
217
- # 1. Create OpenAPI spec with specific parameter configuration
218
- spec = {"openapi": "3.1.0", ...}
219
-
220
- # 2. Parse and create components
221
- routes = parse_openapi_to_http_routes(spec)
222
- tool = OpenAPITool(mock_client, routes[0], ...)
223
-
224
- # 3. Execute and verify request parameters
225
- await tool.run({"param": "value"})
226
- actual_params = mock_client.request.call_args.kwargs["params"]
227
- assert actual_params == expected_params
228
- ```
229
-
230
- ## Testing
231
-
232
- OpenAPI functionality is tested across multiple files in `tests/server/openapi/`:
233
-
234
- - `test_basic_functionality.py` - Core component creation and execution
235
- - `test_explode_integration.py` - Parameter explode behavior
236
- - `test_deepobject_style.py` - DeepObject style parameter encoding
237
- - `test_parameter_collisions.py` - Parameter name collision handling
238
- - `test_openapi_path_parameters.py` - Path parameter serialization
239
- - `test_configuration.py` - Route mapping and MCP names
240
- - `test_description_propagation.py` - Schema and description handling
241
-
242
- When adding new OpenAPI features, create focused test files rather than adding to existing monolithic files.
243
-
244
- ---
245
-
246
- *This document should be updated when new OpenAPI features are added or when edge cases are discovered and addressed.*
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
Windows_Notes.md DELETED
@@ -1,58 +0,0 @@
1
- # Getting your development environment set up properly
2
- To get your environment up and running properly, you'll need a slightly different set of commands that are windows specific:
3
- ```bash
4
- uv venv
5
- .venv\Scripts\activate
6
- uv pip install -e ".[dev]"
7
- ```
8
-
9
- This will install the package in editable mode, and install the development dependencies.
10
-
11
-
12
- # Fixing `AttributeError: module 'collections' has no attribute 'Callable'`
13
- - open `.venv\Lib\site-packages\pyreadline\py3k_compat.py`
14
- - change `return isinstance(x, collections.Callable)` to
15
- ```
16
- from collections.abc import Callable
17
- return isinstance(x, Callable)
18
- ```
19
-
20
- # Helpful notes
21
- For developing FastMCP
22
- ## Install local development version of FastMCP into a local FastMCP project server
23
- - ensure
24
- - change directories to your FastMCP Server location so you can install it in your .venv
25
- - run `.venv\Scripts\activate` to activate your virtual environment
26
- - Then run a series of commands to uninstall the old version and install the new
27
- ```bash
28
- # First uninstall
29
- uv pip uninstall fastmcp
30
-
31
- # Clean any build artifacts in your fastmcp directory
32
- cd C:\path\to\fastmcp
33
- del /s /q *.egg-info
34
-
35
- # Then reinstall in your weather project
36
- cd C:\path\to\new\fastmcp_server
37
- uv pip install --no-cache-dir -e C:\Users\justj\PycharmProjects\fastmcp
38
-
39
- # Check that it installed properly and has the correct git hash
40
- pip show fastmcp
41
- ```
42
-
43
- ## Running the FastMCP server with Inspector
44
- MCP comes with a node.js application called Inspector that can be used to inspect the FastMCP server. To run the inspector, you'll need to install node.js and npm. Then you can run the following commands:
45
- ```bash
46
- fastmcp dev server.py
47
- ```
48
- This will launch a web app on http://localhost:5173/ that you can use to inspect the FastMCP server.
49
-
50
- ## If you start development before creating a fork - your get out of jail free card
51
- - Add your fork as a new remote to your local repository `git remote add fork git@github.com:YOUR-USERNAME/REPOSITORY-NAME.git`
52
- - This will add your repo, short named 'fork', as a remote to your local repository
53
- - Verify that it was added correctly by running `git remote -v`
54
- - Commit your changes
55
- - Push your changes to your fork `git push fork <branch>`
56
- - Create your pull request on GitHub
57
-
58
-
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
build.json CHANGED
@@ -1,5 +1,5 @@
1
  {
2
  "repository": "PureCipher/xsecuremcp2.0",
3
- "commit": "b8f75f12f0f1f7331917a7785111bd3b1ffd4a06",
4
- "version": "0.0.1.dev4088+b8f75f12"
5
  }
 
1
  {
2
  "repository": "PureCipher/xsecuremcp2.0",
3
+ "commit": "5bd407c3b7812ee3596ef0e1eea9afa5ecff0534",
4
+ "version": "0.0.1.dev4090+5bd407c3"
5
  }
docs/.cursor/rules/mintlify.mdc DELETED
@@ -1,364 +0,0 @@
1
- ---
2
- description:
3
- globs: *.mdx
4
- alwaysApply: false
5
- ---
6
- # Mintlify technical writing assistant
7
-
8
- You are an AI writing assistant specialized in creating exceptional technical documentation using Mintlify components and following industry-leading technical writing practices.
9
-
10
- ## Core writing principles
11
-
12
- ### Language and style requirements
13
- - Use clear, direct language appropriate for technical audiences
14
- - Write in second person ("you") for instructions and procedures
15
- - Use active voice over passive voice
16
- - Employ present tense for current states, future tense for outcomes
17
- - Maintain consistent terminology throughout all documentation
18
- - Keep sentences concise while providing necessary context
19
- - Use parallel structure in lists, headings, and procedures
20
-
21
- ### Content organization standards
22
- - Lead with the most important information (inverted pyramid structure)
23
- - Use progressive disclosure: basic concepts before advanced ones
24
- - Break complex procedures into numbered steps
25
- - Include prerequisites and context before instructions
26
- - Provide expected outcomes for each major step
27
- - End sections with next steps or related information
28
- - Use descriptive, keyword-rich headings for navigation and SEO
29
-
30
- ### User-centered approach
31
- - Focus on user goals and outcomes rather than system features
32
- - Anticipate common questions and address them proactively
33
- - Include troubleshooting for likely failure points
34
- - Provide multiple pathways when appropriate (beginner vs advanced), but offer an opinionated path for people to follow to avoid overwhelming with options
35
-
36
- ## Mintlify component reference
37
-
38
- ### Callout components
39
-
40
- #### Note - Additional helpful information
41
-
42
- <Note>
43
- Supplementary information that supports the main content without interrupting flow
44
- </Note>
45
-
46
- #### Tip - Best practices and pro tips
47
-
48
- <Tip>
49
- Expert advice, shortcuts, or best practices that enhance user success
50
- </Tip>
51
-
52
- #### Warning - Important cautions
53
-
54
- <Warning>
55
- Critical information about potential issues, breaking changes, or destructive actions
56
- </Warning>
57
-
58
- #### Info - Neutral contextual information
59
-
60
- <Info>
61
- Background information, context, or neutral announcements
62
- </Info>
63
-
64
- #### Check - Success confirmations
65
-
66
- <Check>
67
- Positive confirmations, successful completions, or achievement indicators
68
- </Check>
69
-
70
- ### Code components
71
-
72
- #### Single code block
73
-
74
- ```javascript config.js
75
- const apiConfig = {
76
- baseURL: 'https://api.example.com',
77
- timeout: 5000,
78
- headers: {
79
- 'Authorization': `Bearer ${process.env.API_TOKEN}`
80
- }
81
- };
82
- ```
83
-
84
- #### Code group with multiple languages
85
-
86
- <CodeGroup>
87
- ```javascript Node.js
88
- const response = await fetch('/api/endpoint', {
89
- headers: { Authorization: `Bearer ${apiKey}` }
90
- });
91
- ```
92
-
93
- ```python Python
94
- import requests
95
- response = requests.get('/api/endpoint',
96
- headers={'Authorization': f'Bearer {api_key}'})
97
- ```
98
-
99
- ```curl cURL
100
- curl -X GET '/api/endpoint' \
101
- -H 'Authorization: Bearer YOUR_API_KEY'
102
- ```
103
- </CodeGroup>
104
-
105
- #### Request/Response examples
106
-
107
- <RequestExample>
108
- ```bash cURL
109
- curl -X POST 'https://api.example.com/users' \
110
- -H 'Content-Type: application/json' \
111
- -d '{"name": "John Doe", "email": "john@example.com"}'
112
- ```
113
- </RequestExample>
114
-
115
- <ResponseExample>
116
- ```json Success
117
- {
118
- "id": "user_123",
119
- "name": "John Doe",
120
- "email": "john@example.com",
121
- "created_at": "2024-01-15T10:30:00Z"
122
- }
123
- ```
124
- </ResponseExample>
125
-
126
- ### Structural components
127
-
128
- #### Steps for procedures
129
-
130
- <Steps>
131
- <Step title="Install dependencies">
132
- Run `npm install` to install required packages.
133
-
134
- <Check>
135
- Verify installation by running `npm list`.
136
- </Check>
137
- </Step>
138
-
139
- <Step title="Configure environment">
140
- Create a `.env` file with your API credentials.
141
-
142
- ```bash
143
- API_KEY=your_api_key_here
144
- ```
145
-
146
- <Warning>
147
- Never commit API keys to version control.
148
- </Warning>
149
- </Step>
150
- </Steps>
151
-
152
- #### Tabs for alternative content
153
-
154
- <Tabs>
155
- <Tab title="macOS">
156
- ```bash
157
- brew install node
158
- npm install -g package-name
159
- ```
160
- </Tab>
161
-
162
- <Tab title="Windows">
163
- ```powershell
164
- choco install nodejs
165
- npm install -g package-name
166
- ```
167
- </Tab>
168
-
169
- <Tab title="Linux">
170
- ```bash
171
- sudo apt install nodejs npm
172
- npm install -g package-name
173
- ```
174
- </Tab>
175
- </Tabs>
176
-
177
- #### Accordions for collapsible content
178
-
179
- <AccordionGroup>
180
- <Accordion title="Troubleshooting connection issues">
181
- - **Firewall blocking**: Ensure ports 80 and 443 are open
182
- - **Proxy configuration**: Set HTTP_PROXY environment variable
183
- - **DNS resolution**: Try using 8.8.8.8 as DNS server
184
- </Accordion>
185
-
186
- <Accordion title="Advanced configuration">
187
- ```javascript
188
- const config = {
189
- performance: { cache: true, timeout: 30000 },
190
- security: { encryption: 'AES-256' }
191
- };
192
- ```
193
- </Accordion>
194
- </AccordionGroup>
195
-
196
- ### API documentation components
197
-
198
- #### Parameter fields
199
-
200
- <ParamField path="user_id" type="string" required>
201
- Unique identifier for the user. Must be a valid UUID v4 format.
202
- </ParamField>
203
-
204
- <ParamField body="email" type="string" required>
205
- User's email address. Must be valid and unique within the system.
206
- </ParamField>
207
-
208
- <ParamField query="limit" type="integer" default="10">
209
- Maximum number of results to return. Range: 1-100.
210
- </ParamField>
211
-
212
- <ParamField header="Authorization" type="string" required>
213
- Bearer token for API authentication. Format: `Bearer YOUR_API_KEY`
214
- </ParamField>
215
-
216
- #### Response fields
217
-
218
- <ResponseField name="user_id" type="string" required>
219
- Unique identifier assigned to the newly created user.
220
- </ResponseField>
221
-
222
- <ResponseField name="created_at" type="timestamp">
223
- ISO 8601 formatted timestamp of when the user was created.
224
- </ResponseField>
225
-
226
- <ResponseField name="permissions" type="array">
227
- List of permission strings assigned to this user.
228
- </ResponseField>
229
-
230
- #### Expandable nested fields
231
-
232
- <ResponseField name="user" type="object">
233
- Complete user object with all associated data.
234
-
235
- <Expandable title="User properties">
236
- <ResponseField name="profile" type="object">
237
- User profile information including personal details.
238
-
239
- <Expandable title="Profile details">
240
- <ResponseField name="first_name" type="string">
241
- User's first name as entered during registration.
242
- </ResponseField>
243
-
244
- <ResponseField name="avatar_url" type="string | null">
245
- URL to user's profile picture. Returns null if no avatar is set.
246
- </ResponseField>
247
- </Expandable>
248
- </ResponseField>
249
- </Expandable>
250
- </ResponseField>
251
-
252
- ### Interactive components
253
-
254
- #### Cards for navigation
255
-
256
- <Card title="Getting started guide" icon="rocket" href="/quickstart">
257
- Complete walkthrough from installation to your first API call in under 10 minutes.
258
- </Card>
259
-
260
- <CardGroup cols={2}>
261
- <Card title="Authentication" icon="key" href="/auth">
262
- Learn how to authenticate requests using API keys or JWT tokens.
263
- </Card>
264
-
265
- <Card title="Rate limiting" icon="clock" href="/rate-limits">
266
- Understand rate limits and best practices for high-volume usage.
267
- </Card>
268
- </CardGroup>
269
-
270
- ### Media and advanced components
271
-
272
- #### Frames for images
273
-
274
- Wrap all images in frames.
275
-
276
- <Frame>
277
- <img src="/images/dashboard.png" alt="Main dashboard showing analytics overview" />
278
- </Frame>
279
-
280
- <Frame caption="The analytics dashboard provides real-time insights">
281
- <img src="/images/analytics.png" alt="Analytics dashboard with charts" />
282
- </Frame>
283
-
284
- #### Tooltips and updates
285
-
286
- <Tooltip tip="Application Programming Interface - protocols for building software">
287
- API
288
- </Tooltip>
289
-
290
- <Update label="Version 2.1.0" description="Released March 15, 2024">
291
- ## New features
292
- - Added bulk user import functionality
293
- - Improved error messages with actionable suggestions
294
-
295
- ## Bug fixes
296
- - Fixed pagination issue with large datasets
297
- - Resolved authentication timeout problems
298
- </Update>
299
-
300
- ## Required page structure
301
-
302
- Every documentation page must begin with YAML frontmatter:
303
-
304
- ```yaml
305
- ---
306
- title: "Clear, specific, keyword-rich title"
307
- description: "Concise description explaining page purpose and value"
308
- ---
309
- ```
310
-
311
- ## Content quality standards
312
-
313
- ### Code examples requirements
314
- - Always include complete, runnable examples that users can copy and execute
315
- - Show proper error handling and edge case management
316
- - Use realistic data instead of placeholder values
317
- - Include expected outputs and results for verification
318
- - Test all code examples thoroughly before publishing
319
- - Specify language and include filename when relevant
320
- - Add explanatory comments for complex logic
321
-
322
- ### API documentation requirements
323
- - Document all parameters including optional ones with clear descriptions
324
- - Show both success and error response examples with realistic data
325
- - Include rate limiting information with specific limits
326
- - Provide authentication examples showing proper format
327
- - Explain all HTTP status codes and error handling
328
- - Cover complete request/response cycles
329
-
330
- ### Accessibility requirements
331
- - Include descriptive alt text for all images and diagrams
332
- - Use specific, actionable link text instead of "click here"
333
- - Ensure proper heading hierarchy starting with H2
334
- - Provide keyboard navigation considerations
335
- - Use sufficient color contrast in examples and visuals
336
- - Structure content for easy scanning with headers and lists
337
-
338
- ## AI assistant instructions
339
-
340
- ### Component selection logic
341
- - Use **Steps** for procedures, tutorials, setup guides, and sequential instructions
342
- - Use **Tabs** for platform-specific content or alternative approaches
343
- - Use **CodeGroup** when showing the same concept in multiple languages
344
- - Use **Accordions** for supplementary information that might interrupt flow
345
- - Use **Cards and CardGroup** for navigation, feature overviews, and related resources
346
- - Use **RequestExample/ResponseExample** specifically for API endpoint documentation
347
- - Use **ParamField** for API parameters, **ResponseField** for API responses
348
- - Use **Expandable** for nested object properties or hierarchical information
349
-
350
- ### Quality assurance checklist
351
- - Verify all code examples are syntactically correct and executable
352
- - Test all links to ensure they are functional and lead to relevant content
353
- - Validate Mintlify component syntax with all required properties
354
- - Confirm proper heading hierarchy with H2 for main sections, H3 for subsections
355
- - Ensure content flows logically from basic concepts to advanced topics
356
- - Check for consistency in terminology, formatting, and component usage
357
-
358
- ### Error prevention strategies
359
- - Always include realistic error handling in code examples
360
- - Provide dedicated troubleshooting sections for complex procedures
361
- - Explain prerequisites clearly before beginning instructions
362
- - Include verification and testing steps with expected outcomes
363
- - Add appropriate warnings for destructive or security-sensitive actions
364
- - Validate all technical information through testing before publication
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
docs/REFLEXIVE_CORE_WHITEPAPER.md DELETED
@@ -1,633 +0,0 @@
1
- # Reflexive Core: A Self-Monitoring and Self-Correcting Runtime for Secure MCP
2
-
3
- ## Executive Summary
4
-
5
- The Reflexive Core represents a paradigm shift in Model Context Protocol (MCP) security architecture, introducing autonomous self-monitoring and self-correcting capabilities that enable real-time threat detection, policy enforcement, and automated incident response. This whitepaper presents the technical architecture, implementation details, and security guarantees of a reflexive runtime system that continuously monitors MCP operations for anomalies, policy violations, and ledger inconsistencies while automatically taking corrective actions.
6
-
7
- ## Table of Contents
8
-
9
- 1. [Introduction](#introduction)
10
- 2. [Architecture Overview](#architecture-overview)
11
- 3. [Core Components](#core-components)
12
- 4. [Security Model](#security-model)
13
- 5. [Implementation Details](#implementation-details)
14
- 6. [Performance Characteristics](#performance-characteristics)
15
- 7. [Security Analysis](#security-analysis)
16
- 8. [Future Enhancements](#future-enhancements)
17
- 9. [Conclusion](#conclusion)
18
-
19
- ## Introduction
20
-
21
- ### Problem Statement
22
-
23
- Traditional MCP implementations rely on static policy enforcement and manual intervention for security incident response. This reactive approach creates several critical vulnerabilities:
24
-
25
- 1. **Temporal Gaps**: Time between threat detection and response allows for exploitation
26
- 2. **Human Bottlenecks**: Manual intervention introduces delays and potential errors
27
- 3. **Incomplete Coverage**: Static policies cannot adapt to novel attack vectors
28
- 4. **Audit Complexity**: Manual correlation of events across distributed systems
29
- 5. **Compliance Gaps**: Inconsistent enforcement of regulatory requirements
30
-
31
- ### Solution Architecture
32
-
33
- The Reflexive Core addresses these limitations through a multi-layered, event-driven architecture that provides:
34
-
35
- - **Continuous Monitoring**: Real-time analysis of all MCP operations
36
- - **Automated Response**: Immediate corrective actions without human intervention
37
- - **Adaptive Policies**: Dynamic policy adjustment based on threat intelligence
38
- - **Cryptographic Auditability**: Tamper-evident logging with proof chains
39
- - **Self-Healing**: Automatic recovery from detected anomalies
40
-
41
- ## Architecture Overview
42
-
43
- ### System Design Principles
44
-
45
- The Reflexive Core is built on four fundamental principles:
46
-
47
- 1. **Autonomy**: The system operates independently with minimal human oversight
48
- 2. **Transparency**: All decisions and actions are cryptographically verifiable
49
- 3. **Resilience**: The system continues operating even when components fail
50
- 4. **Extensibility**: New monitoring and response capabilities can be added dynamically
51
-
52
- ### High-Level Architecture
53
-
54
- ```
55
- ┌─────────────────────────────────────────────────────────────────┐
56
- │ Reflexive Core Runtime │
57
- ├─────────────────────────────────────────────────────────────────┤
58
- │ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ │
59
- │ │ Policy │ │ Ledger │ │ Anomaly │ │
60
- │ │ Monitor │ │ Monitor │ │ Detector │ │
61
- │ └─────────────┘ └─────────────┘ └─────────────┘ │
62
- │ │ │ │ │
63
- │ └────────────────┼────────────────┘ │
64
- │ │ │
65
- │ ┌─────────────────────────────────────────────────────────┐ │
66
- │ │ Reflexive Engine │ │
67
- │ │ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ │ │
68
- │ │ │ Event │ │ Decision │ │ Action │ │ │
69
- │ │ │ Processor │ │ Engine │ │ Executor │ │ │
70
- │ │ └─────────────┘ └─────────────┘ └─────────────┘ │ │
71
- │ └─────────────────────────────────────────────────────────┘ │
72
- │ │ │
73
- │ ┌────────────────────��────────────────────────────────────┐ │
74
- │ │ Action Framework │ │
75
- │ │ ┌─────────┐ ┌─────────┐ ┌─────────┐ ┌─────────┐ │ │
76
- │ │ │ Halt │ │Escalate │ │ Monitor │ │ Allow │ │ │
77
- │ │ └─────────┘ └─────────┘ └─────────┘ └─────────┘ │ │
78
- │ └─────────────────────────────────────────────────────────┘ │
79
- └─────────────────────────────────────────────────────────────────┘
80
- ```
81
-
82
- ### Event Flow Architecture
83
-
84
- The system processes events through a multi-stage pipeline:
85
-
86
- 1. **Event Ingestion**: Actions are submitted to the reflexive engine
87
- 2. **Parallel Monitoring**: Multiple monitors analyze the action simultaneously
88
- 3. **Risk Assessment**: The engine evaluates combined monitor outputs
89
- 4. **Decision Making**: Appropriate response actions are determined
90
- 5. **Action Execution**: Corrective actions are executed automatically
91
- 6. **Audit Logging**: All decisions and actions are cryptographically logged
92
-
93
- ## Core Components
94
-
95
- ### ReflexiveEngine
96
-
97
- The `ReflexiveEngine` serves as the central orchestrator, implementing a sophisticated decision-making system based on multi-dimensional risk assessment.
98
-
99
- #### Key Features
100
-
101
- - **Asynchronous Event Processing**: Non-blocking event queue with configurable timeouts
102
- - **Dynamic Monitor Registration**: Monitors can be added/removed at runtime
103
- - **Risk-Based Decision Making**: Sophisticated risk assessment algorithm
104
- - **Cryptographic Integrity**: All decisions include tamper-evident proof hashes
105
-
106
- #### Risk Assessment Algorithm
107
-
108
- The engine employs a multi-factor risk assessment model:
109
-
110
- ```python
111
- def _assess_risk_level(self, violations: List[Dict], anomalies: List[Dict]) -> RiskLevel:
112
- """Multi-dimensional risk assessment algorithm."""
113
-
114
- # Critical risk factors
115
- critical_violations = [v for v in violations if v.get("severity") == "critical"]
116
- critical_anomalies = [a for a in anomalies if a.get("severity") == "critical"]
117
- if critical_violations or critical_anomalies:
118
- return RiskLevel.CRITICAL
119
-
120
- # High risk factors
121
- high_violations = [v for v in violations if v.get("severity") == "high"]
122
- high_anomalies = [a for a in anomalies if a.get("severity") == "high"]
123
- total_issues = len(violations) + len(anomalies)
124
-
125
- if high_violations or high_anomalies or total_issues >= 5:
126
- return RiskLevel.HIGH
127
-
128
- # Medium risk factors
129
- medium_violations = [v for v in violations if v.get("severity") == "medium"]
130
- medium_anomalies = [a for a in anomalies if a.get("severity") == "medium"]
131
-
132
- if medium_violations or medium_anomalies or total_issues >= 2:
133
- return RiskLevel.MEDIUM
134
-
135
- return RiskLevel.LOW
136
- ```
137
-
138
- #### Decision Matrix
139
-
140
- The engine implements a sophisticated decision matrix that maps risk levels to appropriate actions:
141
-
142
- | Risk Level | Primary Action | Secondary Action | Escalation Target |
143
- |------------|----------------|------------------|-------------------|
144
- | CRITICAL | HALT | ESCALATE | security_admin |
145
- | HIGH | HALT | ESCALATE | system_admin |
146
- | MEDIUM | ESCALATE | MONITOR | monitoring_team |
147
- | LOW | MONITOR | ALLOW | - |
148
-
149
- ### Monitoring Components
150
-
151
- #### PolicyMonitor
152
-
153
- The `PolicyMonitor` implements real-time policy enforcement with sophisticated pattern recognition:
154
-
155
- **Detection Capabilities:**
156
- - **Administrative Access Violations**: Detects unauthorized privilege escalation attempts
157
- - **Rate Limiting**: Identifies potential DoS attacks through frequency analysis
158
- - **Resource Access Patterns**: Monitors access to sensitive resources
159
- - **Session Anomalies**: Detects unusual session behavior patterns
160
-
161
- **Implementation Highlights:**
162
- ```python
163
- async def _check_policy_violations(self, action_context) -> List[Dict[str, Any]]:
164
- """Advanced policy violation detection."""
165
- violations = []
166
-
167
- # Guest user admin access detection
168
- if (action_context.action_type == "admin_access" and
169
- action_context.actor_id.startswith("guest")):
170
- violations.append({
171
- "rule": "admin_access_restriction",
172
- "message": "Guest user attempting admin access",
173
- "severity": "high"
174
- })
175
-
176
- # Temporal rate limiting with sliding window
177
- recent_violations = [
178
- v for v in self.violation_history
179
- if (v.get("actor_id") == action_context.actor_id and
180
- datetime.fromisoformat(v["timestamp"]) >
181
- datetime.utcnow() - timedelta(minutes=5))
182
- ]
183
-
184
- if len(recent_violations) >= 3:
185
- violations.append({
186
- "rule": "rate_limit_exceeded",
187
- "message": f"Actor {action_context.actor_id} has {len(recent_violations)} recent violations",
188
- "severity": "medium"
189
- })
190
-
191
- return violations
192
- ```
193
-
194
- #### AnomalyDetector
195
-
196
- The `AnomalyDetector` employs behavioral analysis and statistical modeling to identify anomalous patterns:
197
-
198
- **Detection Algorithms:**
199
- - **Frequency Analysis**: Detects unusual action frequency patterns
200
- - **Temporal Analysis**: Identifies actions occurring at unusual times
201
- - **Resource Access Patterns**: Monitors first-time resource access
202
- - **Privilege Escalation Detection**: Identifies privilege escalation attempts
203
-
204
- **Behavioral Modeling:**
205
- ```python
206
- def _update_patterns(self, action_context):
207
- """Update behavioral patterns for anomaly detection."""
208
- actor_id = action_context.actor_id
209
- actor_data = self.actor_patterns[actor_id]
210
-
211
- # Update action frequency patterns
212
- actor_data["action_counts"][action_context.action_type] += 1
213
- self.global_patterns["action_frequency"][action_context.action_type] += 1
214
-
215
- # Update resource access patterns
216
- if action_context.resource_id:
217
- actor_data["resource_access"][action_context.resource_id] += 1
218
- self.global_patterns["resource_access"][action_context.resource_id] += 1
219
-
220
- # Update temporal patterns
221
- hour = action_context.timestamp.hour
222
- self.global_patterns["time_patterns"][hour] += 1
223
- ```
224
-
225
- #### LedgerMonitor
226
-
227
- The `LedgerMonitor` ensures the integrity of the provenance ledger through continuous validation:
228
-
229
- **Integrity Checks:**
230
- - **Chain Integrity**: Validates hash-linked chain structure
231
- - **Block Completeness**: Ensures no missing blocks in the sequence
232
- - **Merkle Tree Validation**: Verifies Merkle tree root calculations
233
- - **Temporal Consistency**: Validates timestamp ordering
234
-
235
- ### Action Framework
236
-
237
- The action framework provides a comprehensive set of corrective actions with different severity levels and execution modes.
238
-
239
- #### HaltAction
240
-
241
- Implements immediate or graceful operation termination:
242
-
243
- ```python
244
- async def execute(self) -> Dict[str, Any]:
245
- """Execute halt action with configurable severity."""
246
- try:
247
- self.status = "executing"
248
-
249
- # Log critical halt decision
250
- logger.critical(f"HALTING OPERATIONS: {self.halt_reason}")
251
- logger.critical(f"Affected operations: {self.affected_operations}")
252
- logger.critical(f"Decision ID: {self.decision.decision_id}")
253
-
254
- # Execute halt based on level
255
- if self.halt_level == "immediate":
256
- # Immediate termination of all affected operations
257
- await self._immediate_halt()
258
- elif self.halt_level == "graceful":
259
- # Graceful shutdown allowing cleanup
260
- await self._graceful_halt()
261
-
262
- return {
263
- "halted_operations": self.affected_operations,
264
- "halt_timestamp": self.timestamp.isoformat(),
265
- "halt_reason": self.halt_reason,
266
- "halt_level": self.halt_level,
267
- "decision_id": str(self.decision.decision_id)
268
- }
269
- except Exception as e:
270
- self.status = "failed"
271
- raise
272
- ```
273
-
274
- #### EscalateAction
275
-
276
- Implements automated escalation with configurable notification channels:
277
-
278
- ```python
279
- async def execute(self) -> Dict[str, Any]:
280
- """Execute escalation with multi-channel notification."""
281
- try:
282
- self.status = "executing"
283
-
284
- # Log escalation decision
285
- logger.warning(f"ESCALATING TO {self.escalation_target}: {self.decision.reason}")
286
- logger.warning(f"Priority: {self.escalation_priority}")
287
-
288
- # Execute escalation
289
- escalation_result = {
290
- "escalation_target": self.escalation_target,
291
- "escalation_priority": self.escalation_priority,
292
- "escalation_timestamp": self.timestamp.isoformat(),
293
- "escalation_context": self.escalation_context,
294
- "notification_channels": self.notification_channels,
295
- "decision_id": str(self.decision.decision_id),
296
- "action_context": self.decision.action_context.model_dump(mode='json')
297
- }
298
-
299
- # Send notifications via configured channels
300
- await self._send_notifications(escalation_result)
301
-
302
- return escalation_result
303
- except Exception as e:
304
- self.status = "failed"
305
- raise
306
- ```
307
-
308
- ## Security Model
309
-
310
- ### Threat Model
311
-
312
- The Reflexive Core is designed to protect against the following threat categories:
313
-
314
- 1. **Insider Threats**: Malicious or compromised internal actors
315
- 2. **External Attacks**: Unauthorized external access attempts
316
- 3. **System Compromise**: Compromised system components
317
- 4. **Data Exfiltration**: Unauthorized data access and extraction
318
- 5. **Service Disruption**: DoS attacks and system availability threats
319
-
320
- ### Security Guarantees
321
-
322
- #### Cryptographic Integrity
323
-
324
- All reflexive decisions include cryptographic proof hashes that provide:
325
-
326
- - **Non-repudiation**: Decisions cannot be denied by the system
327
- - **Integrity Verification**: Any tampering with decisions is detectable
328
- - **Audit Trail**: Complete, verifiable history of all decisions
329
-
330
- ```python
331
- def get_decision_hash(self) -> str:
332
- """Generate tamper-evident proof hash."""
333
- content = {
334
- "decision_id": str(self.decision_id),
335
- "decision_type": self.decision_type,
336
- "risk_level": self.risk_level,
337
- "action_context": self.action_context.model_dump(),
338
- "reason": self.reason,
339
- "evidence": self.evidence,
340
- "escalated_to": self.escalated_to
341
- }
342
- content_str = json.dumps(content, sort_keys=True, default=str)
343
- return hashlib.sha256(content_str.encode()).hexdigest()
344
- ```
345
-
346
- #### Fail-Safe Design
347
-
348
- The system implements multiple fail-safe mechanisms:
349
-
350
- 1. **Default Deny**: Unknown or suspicious actions are denied by default
351
- 2. **Graceful Degradation**: System continues operating even when components fail
352
- 3. **Circuit Breakers**: Automatic isolation of failing components
353
- 4. **Rate Limiting**: Protection against resource exhaustion attacks
354
-
355
- #### Zero-Trust Architecture
356
-
357
- The Reflexive Core operates on zero-trust principles:
358
-
359
- - **Continuous Verification**: All actions are verified regardless of source
360
- - **Least Privilege**: Actions are granted minimum necessary permissions
361
- - **Defense in Depth**: Multiple layers of security controls
362
- - **Assume Breach**: System designed to operate securely even when compromised
363
-
364
- ## Implementation Details
365
-
366
- ### Asynchronous Architecture
367
-
368
- The system is built on an asynchronous, event-driven architecture that provides:
369
-
370
- - **High Throughput**: Non-blocking event processing
371
- - **Low Latency**: Immediate response to security events
372
- - **Scalability**: Horizontal scaling through event distribution
373
- - **Resilience**: Fault tolerance through async error handling
374
-
375
- ```python
376
- async def _process_events(self):
377
- """Main event processing loop with fault tolerance."""
378
- while self.is_running:
379
- try:
380
- # Wait for events with timeout
381
- event = await asyncio.wait_for(self.event_queue.get(), timeout=1.0)
382
- await self._handle_event(event)
383
- except asyncio.TimeoutError:
384
- # No events, continue
385
- continue
386
- except Exception as e:
387
- logger.error(f"Error processing reflexive event: {e}")
388
- # Continue processing despite errors
389
- ```
390
-
391
- ### Dynamic Monitor Registration
392
-
393
- The system supports dynamic addition and removal of monitors:
394
-
395
- ```python
396
- def add_monitor(self, monitor: Callable):
397
- """Add a monitor function to the reflexive engine."""
398
- self.monitors.append(monitor)
399
- logger.info(f"Added monitor: {monitor.__name__}")
400
-
401
- def remove_monitor(self, monitor: Callable):
402
- """Remove a monitor function from the reflexive engine."""
403
- if monitor in self.monitors:
404
- self.monitors.remove(monitor)
405
- logger.info(f"Removed monitor: {monitor.__name__}")
406
- ```
407
-
408
- ### HTTP API Design
409
-
410
- The RESTful API provides comprehensive access to reflexive core functionality:
411
-
412
- #### Risk Simulation Endpoint
413
-
414
- ```python
415
- @router.post("/core/simulate-risk")
416
- async def simulate_risk_endpoint(request: Request) -> JSONResponse:
417
- """Simulate risk scenarios for testing and validation."""
418
- try:
419
- body = await request.json()
420
- reflexive_engine: ReflexiveEngine = request.app.state.reflexive_engine
421
-
422
- # Simulate the risk scenario
423
- decision = await reflexive_engine.simulate_risk(body)
424
-
425
- # Create and execute the corresponding action
426
- action = ActionFactory.create_action(decision)
427
- executor = ActionExecutor()
428
- action_result = await executor.execute_action(action)
429
-
430
- return JSONResponse(
431
- status_code=200,
432
- content={
433
- "simulation_id": str(decision.decision_id),
434
- "decision": {
435
- "decision_id": str(decision.decision_id),
436
- "decision_type": decision.decision_type,
437
- "risk_level": decision.risk_level,
438
- "reason": decision.reason,
439
- "evidence": decision.evidence,
440
- "proof_hash": decision.proof_hash,
441
- "escalated_to": decision.escalated_to,
442
- "timestamp": decision.timestamp.isoformat()
443
- },
444
- "action": {
445
- "action_id": str(action.action_id),
446
- "action_type": action.get_action_type(),
447
- "status": action.status,
448
- "result": action_result
449
- },
450
- "action_context": decision.action_context.model_dump(mode='json')
451
- }
452
- )
453
- except Exception as e:
454
- logger.error(f"Failed to simulate risk: {e}")
455
- return JSONResponse(status_code=500, content={"error": str(e)})
456
- ```
457
-
458
- ## Performance Characteristics
459
-
460
- ### Latency Analysis
461
-
462
- The Reflexive Core is designed for low-latency operation:
463
-
464
- - **Event Processing**: < 1ms for simple policy checks
465
- - **Risk Assessment**: < 5ms for complex multi-factor analysis
466
- - **Action Execution**: < 10ms for halt actions, < 100ms for escalations
467
- - **End-to-End Response**: < 50ms for critical security events
468
-
469
- ### Throughput Metrics
470
-
471
- Performance benchmarks under various load conditions:
472
-
473
- | Load Level | Events/sec | Avg Latency | 95th Percentile | Memory Usage |
474
- |------------|------------|-------------|-----------------|--------------|
475
- | Light | 1,000 | 2ms | 5ms | 50MB |
476
- | Medium | 10,000 | 8ms | 20ms | 200MB |
477
- | Heavy | 50,000 | 25ms | 60ms | 800MB |
478
- | Peak | 100,000 | 50ms | 120ms | 1.5GB |
479
-
480
- ### Scalability Characteristics
481
-
482
- The system exhibits linear scalability characteristics:
483
-
484
- - **Horizontal Scaling**: Linear scaling with additional processing nodes
485
- - **Memory Usage**: O(n) where n is the number of active sessions
486
- - **CPU Usage**: O(m) where m is the number of monitors
487
- - **Storage**: O(e) where e is the number of events processed
488
-
489
- ## Security Analysis
490
-
491
- ### Attack Surface Analysis
492
-
493
- The Reflexive Core's attack surface is minimized through:
494
-
495
- 1. **Minimal External Interfaces**: Only essential HTTP endpoints exposed
496
- 2. **Input Validation**: Comprehensive validation of all inputs
497
- 3. **Output Sanitization**: All outputs are sanitized before transmission
498
- 4. **Error Handling**: Secure error handling prevents information leakage
499
-
500
- ### Vulnerability Assessment
501
-
502
- #### Potential Vulnerabilities
503
-
504
- 1. **Monitor Injection**: Malicious monitors could be injected
505
- - **Mitigation**: Monitor signature verification and sandboxing
506
- 2. **Decision Manipulation**: Attackers could attempt to manipulate decisions
507
- - **Mitigation**: Cryptographic proof hashes and immutable audit logs
508
- 3. **Resource Exhaustion**: DoS attacks through excessive event generation
509
- - **Mitigation**: Rate limiting and circuit breakers
510
- 4. **Information Disclosure**: Sensitive information in logs or responses
511
- - **Mitigation**: Data classification and access controls
512
-
513
- #### Security Controls
514
-
515
- The system implements multiple layers of security controls:
516
-
517
- 1. **Authentication**: All API endpoints require authentication
518
- 2. **Authorization**: Role-based access control for different operations
519
- 3. **Encryption**: All data in transit and at rest is encrypted
520
- 4. **Audit Logging**: Comprehensive audit trail for all operations
521
- 5. **Monitoring**: Continuous monitoring of system security posture
522
-
523
- ### Compliance Considerations
524
-
525
- The Reflexive Core supports various compliance frameworks:
526
-
527
- #### SOC 2 Type II
528
- - **Security**: Comprehensive security controls and monitoring
529
- - **Availability**: High availability through fault-tolerant design
530
- - **Processing Integrity**: Cryptographic integrity verification
531
- - **Confidentiality**: Data encryption and access controls
532
- - **Privacy**: Data minimization and privacy controls
533
-
534
- #### ISO 27001
535
- - **Information Security Management**: Comprehensive ISMS implementation
536
- - **Risk Management**: Continuous risk assessment and mitigation
537
- - **Incident Response**: Automated incident detection and response
538
- - **Business Continuity**: Resilient design for business continuity
539
-
540
- #### GDPR
541
- - **Data Protection by Design**: Privacy controls built into the system
542
- - **Data Minimization**: Only necessary data is collected and processed
543
- - **Right to Erasure**: Automated data deletion capabilities
544
- - **Data Portability**: Standardized data export formats
545
-
546
- ## Future Enhancements
547
-
548
- ### Machine Learning Integration
549
-
550
- Future versions will incorporate machine learning capabilities:
551
-
552
- 1. **Anomaly Detection**: ML-based anomaly detection for novel attack patterns
553
- 2. **Threat Intelligence**: Integration with threat intelligence feeds
554
- 3. **Predictive Analytics**: Predictive threat modeling and risk assessment
555
- 4. **Adaptive Policies**: Self-adjusting policies based on threat landscape
556
-
557
- ### Blockchain Integration
558
-
559
- Enhanced audit capabilities through blockchain integration:
560
-
561
- 1. **Immutable Audit Logs**: Blockchain-based audit log storage
562
- 2. **Distributed Verification**: Multi-party verification of decisions
563
- 3. **Smart Contracts**: Automated policy enforcement through smart contracts
564
- 4. **Cross-Chain Interoperability**: Integration with multiple blockchain networks
565
-
566
- ### Advanced Analytics
567
-
568
- Enhanced analytics and reporting capabilities:
569
-
570
- 1. **Real-Time Dashboards**: Live security posture monitoring
571
- 2. **Trend Analysis**: Historical trend analysis and reporting
572
- 3. **Predictive Modeling**: Predictive threat modeling
573
- 4. **Custom Reports**: Configurable reporting and alerting
574
-
575
- ### Integration Ecosystem
576
-
577
- Expanded integration capabilities:
578
-
579
- 1. **SIEM Integration**: Integration with Security Information and Event Management systems
580
- 2. **SOAR Integration**: Security Orchestration, Automation, and Response integration
581
- 3. **Cloud Provider Integration**: Native integration with cloud security services
582
- 4. **Third-Party Tools**: Integration with popular security tools and platforms
583
-
584
- ## Conclusion
585
-
586
- The Reflexive Core represents a significant advancement in MCP security architecture, providing autonomous self-monitoring and self-correcting capabilities that address the fundamental limitations of traditional reactive security approaches. Through its sophisticated multi-layered architecture, the system provides:
587
-
588
- ### Key Achievements
589
-
590
- 1. **Autonomous Security**: Self-monitoring and self-correcting capabilities eliminate human bottlenecks
591
- 2. **Cryptographic Integrity**: Tamper-evident audit trails with cryptographic proof
592
- 3. **Real-Time Response**: Sub-50ms response times for critical security events
593
- 4. **Comprehensive Coverage**: Multi-dimensional threat detection and response
594
- 5. **Extensible Architecture**: Dynamic addition of new monitoring and response capabilities
595
-
596
- ### Technical Innovation
597
-
598
- The Reflexive Core introduces several technical innovations:
599
-
600
- - **Event-Driven Architecture**: Asynchronous, non-blocking event processing
601
- - **Multi-Factor Risk Assessment**: Sophisticated risk modeling and decision making
602
- - **Dynamic Monitor Registration**: Runtime addition of monitoring capabilities
603
- - **Cryptographic Auditability**: Tamper-evident decision logging
604
- - **Fail-Safe Design**: Resilient operation even under attack conditions
605
-
606
- ### Security Impact
607
-
608
- The system provides significant security improvements:
609
-
610
- - **Reduced Attack Surface**: Automated response eliminates manual intervention delays
611
- - **Enhanced Visibility**: Comprehensive monitoring and audit capabilities
612
- - **Improved Compliance**: Built-in support for major compliance frameworks
613
- - **Proactive Defense**: Predictive threat detection and response
614
- - **Operational Resilience**: Continued operation under adverse conditions
615
-
616
- ### Future Outlook
617
-
618
- The Reflexive Core establishes a foundation for next-generation MCP security architectures. Future enhancements will focus on:
619
-
620
- - **Machine Learning Integration**: Advanced threat detection and response
621
- - **Blockchain Integration**: Enhanced audit and verification capabilities
622
- - **Cloud-Native Design**: Optimized for cloud and edge computing environments
623
- - **Ecosystem Integration**: Seamless integration with existing security tools
624
-
625
- The Reflexive Core represents a paradigm shift toward autonomous, self-healing security systems that can adapt to evolving threat landscapes while maintaining the highest standards of security, compliance, and operational excellence.
626
-
627
- ---
628
-
629
- **Document Version**: 1.0
630
- **Last Updated**: 2024
631
- **Authors**: FastMCP Development Team
632
- **Classification**: Technical Whitepaper
633
- **Distribution**: Internal and Partner Access
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
index.html CHANGED
@@ -122,7 +122,7 @@
122
  <li><strong>Try the backend:</strong> use the health request below to inspect this Space. It is the registry service, not a general-purpose agent or the calculator example.</li>
123
  <li><strong>Build a server:</strong> install the matching fork packages, define your tools, and configure <code>SecurityConfig</code> for the controls your application needs.</li>
124
  <li><strong>Connect a client:</strong> point an MCP client at your server’s endpoint. The <a href="https://github.com/PureCipher/xsecuremcp2.0#build-an-mcp-server" target="_blank" rel="noopener noreferrer">server-and-client quickstart</a> demonstrates a tool call and receipt verification.</li>
125
- <li><strong>Check enforcement:</strong> follow the <a href="https://github.com/PureCipher/xsecuremcp2.0/blob/main/docs/using-xsecuremcp.md" target="_blank" rel="noopener noreferrer">worked usage guide</a> to allow one operation, deny another, and understand the resulting evidence.</li>
126
  <li><strong>Share and operate:</strong> use PureCipher Publisher to submit projects to your chosen registry, and the separate xregistry console to manage it. Configure authentication, moderation, and persistent storage for your deployment.</li>
127
  </ol>
128
  <h2 id="what-this-space-runs">What this Space runs</h2>
@@ -197,11 +197,11 @@
197
  <tbody>
198
  <tr>
199
  <td>GitHub source</td>
200
- <td><a href="https://github.com/PureCipher/xsecuremcp2.0/commit/b8f75f12f0f1f7331917a7785111bd3b1ffd4a06" target="_blank" rel="noopener noreferrer"><code>b8f75f12f0f1</code></a></td>
201
  </tr>
202
  <tr>
203
  <td>Package version</td>
204
- <td><code>0.0.1.dev4088+b8f75f12</code></td>
205
  </tr>
206
  <tr>
207
  <td>Build metadata</td>
 
122
  <li><strong>Try the backend:</strong> use the health request below to inspect this Space. It is the registry service, not a general-purpose agent or the calculator example.</li>
123
  <li><strong>Build a server:</strong> install the matching fork packages, define your tools, and configure <code>SecurityConfig</code> for the controls your application needs.</li>
124
  <li><strong>Connect a client:</strong> point an MCP client at your server’s endpoint. The <a href="https://github.com/PureCipher/xsecuremcp2.0#build-an-mcp-server" target="_blank" rel="noopener noreferrer">server-and-client quickstart</a> demonstrates a tool call and receipt verification.</li>
125
+ <li><strong>Check enforcement:</strong> allow one operation, deny another, and inspect the resulting evidence. See the <a href="https://github.com/PureCipher/xsecuremcp2.0#readme" target="_blank" rel="noopener noreferrer">project README</a> for the security configuration and its boundaries.</li>
126
  <li><strong>Share and operate:</strong> use PureCipher Publisher to submit projects to your chosen registry, and the separate xregistry console to manage it. Configure authentication, moderation, and persistent storage for your deployment.</li>
127
  </ol>
128
  <h2 id="what-this-space-runs">What this Space runs</h2>
 
197
  <tbody>
198
  <tr>
199
  <td>GitHub source</td>
200
+ <td><a href="https://github.com/PureCipher/xsecuremcp2.0/commit/5bd407c3b7812ee3596ef0e1eea9afa5ecff0534" target="_blank" rel="noopener noreferrer"><code>5bd407c3b781</code></a></td>
201
  </tr>
202
  <tr>
203
  <td>Package version</td>
204
+ <td><code>0.0.1.dev4090+5bd407c3</code></td>
205
  </tr>
206
  <tr>
207
  <td>Build metadata</td>
wheels/{fastmcp-0.0.1.dev4088+b8f75f12-py3-none-any.whl → fastmcp-0.0.1.dev4090+5bd407c3-py3-none-any.whl} RENAMED
@@ -1,3 +1,3 @@
1
  version https://git-lfs.github.com/spec/v1
2
- oid sha256:fabc181bffa0b8c208d24f98bad2eaf2e559f0a577eb00cc631be717461d26f2
3
- size 358097
 
1
  version https://git-lfs.github.com/spec/v1
2
+ oid sha256:32e444d438ee2c3b531879dd6c94a555d268d9084f18981bf6a06c0fdeb22f47
3
+ size 358043
wheels/{fastmcp_remote-0.0.1.dev4088+b8f75f12-py3-none-any.whl → fastmcp_remote-0.0.1.dev4090+5bd407c3-py3-none-any.whl} RENAMED
Binary files a/wheels/fastmcp_remote-0.0.1.dev4088+b8f75f12-py3-none-any.whl and b/wheels/fastmcp_remote-0.0.1.dev4090+5bd407c3-py3-none-any.whl differ
 
wheels/{fastmcp_slim-0.0.1.dev4088+b8f75f12-py3-none-any.whl → fastmcp_slim-0.0.1.dev4090+5bd407c3-py3-none-any.whl} RENAMED
@@ -1,3 +1,3 @@
1
  version https://git-lfs.github.com/spec/v1
2
- oid sha256:31e663759d38acd877a62f61c8cc710a2e32487b58062fa0f2196cdb36d865d8
3
- size 1339331
 
1
  version https://git-lfs.github.com/spec/v1
2
+ oid sha256:2e2fc37acf3083f22ade3c9af463e1de1969c93a50f58a72554f71af6ecfa2a2
3
+ size 1339330
wheels/{fastmcp_tasks-0.0.1.dev4088+b8f75f12-py3-none-any.whl → fastmcp_tasks-0.0.1.dev4090+5bd407c3-py3-none-any.whl} RENAMED
Binary files a/wheels/fastmcp_tasks-0.0.1.dev4088+b8f75f12-py3-none-any.whl and b/wheels/fastmcp_tasks-0.0.1.dev4090+5bd407c3-py3-none-any.whl differ