9 System Requirements Specification

9.1 Overview

This chapter defines the system requirements for the open-mcp-sysml server per [1, Sec. 2.3.5.3]. Requirements are organized by functional area and traced to stakeholder requirements.

9.2 System Scope and Boundary

9.2.1 System Definition

The open-mcp-sysml server is a software system that implements the Model Context Protocol (MCP) to enable AI-augmented Model-Based Systems Engineering (MBSE) workflows. It provides AI assistants with programmatic access to SysML v2 models stored in Git repositories, with intelligent context management to optimize token usage. The design is provider-agnostic, with GitLab as the reference implementation.

9.2.2 System Boundary

                        ┌───────────────────────────────────┐
                        │         System Boundary           │
                        │                                   │
┌─────────────┐         │  ┌─────────────────────────────┐  │        ┌─────────────┐
│ MCP Client  │◄───────►│  │    open-mcp-sysml            │  │◄──────►│ Git Provider│
│ (External)  │   MCP   │  │                             │  │  HTTP  │  API (Ext.) │
└─────────────┘         │  │  ┌───────┐    ┌───────────┐ │  │        └─────────────┘
                        │  │  │ Tools │    │ Resources │ │  │
                        │  │  └───────┘    └───────────┘ │  │        ┌─────────────┐
                        │  │  ┌───────┐    ┌───────────┐ │  │◄──────►│ SysML v2    │
                        │  │  │Parser │    │  Config   │ │  │  HTTP  │ API Server  │
                        │  │  └───────┘    └───────────┘ │  │        │ (External)  │
                        │  └─────────────────────────────┘  │        └─────────────┘
                        │                                   │
                        └───────────────────────────────────┘

9.2.3 External Interfaces

Interface	Type	Protocol	Description
MCP Client	Input	MCP over stdio/HTTP	AI assistant sending requests
Git Provider API	Output	REST/HTTP	Repository file operations (GitLab reference)
SysML v2 API	Output	REST/HTTP	Model validation and queries
Configuration	Input	Environment variables	Server configuration

Interface Requirements (Tailored)

Per INCOSE Handbook 4.3.4, formal IR-xxx interface requirements are tailored for this project. External interfaces (MCP protocol, Git provider API, SysML v2 API, configuration) are documented in the Architecture Design Description (Section 10.10) rather than duplicated here. This avoids information duplication while maintaining traceability through the RTM (Section 16.3).

9.3 Functional Requirements

9.3.1 Model Context Protocol (MCP)

ID	Requirement	Priority	Verification	Trace
FR-MCP-001	The server SHALL implement MCP protocol version 2024-11-05	High	Test	SR-001
FR-MCP-002	The server SHALL support stdio transport	High	Test	SR-006
FR-MCP-003	The server SHALL support HTTP transport	Medium	Test	SR-003
FR-MCP-004	The server SHALL respond to initialize requests with server capabilities	High	Test	SR-001
FR-MCP-005	The server SHALL list available tools via tools/list	High	Test	SR-001
FR-MCP-006	The server SHALL list available resources via resources/list	High	Test	SR-001

9.3.2 Repository Integration

ID	Requirement	Priority	Verification	Trace
FR-REPO-001	The server SHALL read files from Git repositories	High	Test	SR-001
FR-REPO-002	The server SHALL list .sysml files in a repository directory	High	Test	SR-001
FR-REPO-003	The server SHALL support gitlab.com as a reference target	High	Test	SR-001
FR-REPO-004	The server SHALL support self-hosted Git providers via configurable base URL	Medium	Test	SR-010
FR-REPO-005	The server SHALL authenticate using Personal Access Token	High	Test	SR-001
FR-REPO-006	The server SHALL commit file changes to Git repositories	Medium	Test	SR-001
FR-REPO-007	The server SHALL create merge/pull requests	Low	Test	SR-001

9.3.3 SysML v2 Operations

ID	Requirement	Priority	Verification	Trace
FR-SYS-001	The server SHALL parse SysML v2 textual notation per the grammar subset defined in FR-SYS-008	High	Test	SR-012 SR-013
FR-SYS-002	The server SHALL extract element names and types from parsed models	High	Test	SR-012
FR-SYS-003	The server SHALL validate SysML v2 syntax via API server when available	Medium	Test	SR-011
FR-SYS-004	The server SHALL query model elements by type via API server	Medium	Test	SR-012
FR-SYS-005	The server SHALL provide bundled example SysML v2 models	Low	Inspection	SR-008
FR-SYS-006	The server SHALL parse SysML v2 package, part, action, requirement, and item definitions per OMG SysML v2 grammar	High	Test	SR-013
FR-SYS-007	The server SHALL report parse errors with file path, line number, and column number	High	Test	SR-014
FR-SYS-008	The server SHALL document supported SysML v2 grammar subset with coverage matrix	Medium	Inspection	SR-015
FR-SYS-009	The grammar SHALL be validated against the GfSE SysML v2 model collection as an external test corpus	Medium	Test	SR-013

9.4 Non-Functional Requirements

9.4.1 Performance

ID	Requirement	Priority	Verification	Trace
NFR-PERF-001	The server SHALL respond to tool calls within 5 seconds under normal network conditions	Medium	Test	-
NFR-PERF-002	The server SHALL handle SysML v2 files up to 1MB in size	Medium	Test	-

9.4.2 Security

ID	Requirement	Priority	Verification	Trace
NFR-SEC-001	The server SHALL NOT log authentication tokens to any output	High	Inspection	-
NFR-SEC-002	The server SHALL support configuration via environment variables for secrets	High	Test	-
NFR-SEC-003	The server SHALL validate all input parameters to prevent injection attacks	High	Test	-

9.4.3 Deployment

ID	Requirement	Priority	Verification	Trace
NFR-DEP-001	The server SHALL be distributable as a single static binary with no external runtime dependencies	High	Demonstration	SR-006
NFR-DEP-002	The server SHALL be distributable as an OCI-compliant container image	High	Demonstration	SR-009
NFR-DEP-003	The server SHALL support Linux operating systems (amd64, arm64 architectures)	High	Test	SR-006
NFR-DEP-004	The server SHALL support macOS operating systems (amd64, arm64 architectures)	High	Test	SR-006

9.4.4 Documentation

ID	Requirement	Priority	Verification	Trace
NFR-DOC-001	The software repository SHALL include README with installation instructions	High	Inspection	SR-007
NFR-DOC-002	The software repository SHALL include usage examples	High	Inspection	SR-008
NFR-DOC-003	The software repository SHALL include CONTRIBUTING guide	Medium	Inspection	SR-002

9.5 Constraints and Assumptions

9.5.1 Design Constraints

ID	Constraint	Rationale
DC-001	The server SHALL be implemented in Rust	GKG alignment, memory safety, single static binary
DC-002	The server SHALL use the official Rust MCP SDK (rmcp)	Ensures protocol compliance, official SDK
DC-003	The server SHALL use a provider-agnostic repository interface	Future GKG integration, extensibility
DC-004	Container builds SHALL use Buildah/Podman	OCI-compliant, rootless, CI-friendly
DC-005	The parser SHALL maintain a documented grammar coverage matrix	Transparency about spec compliance

9.5.2 Operational Constraints

ID	Constraint	Impact
OC-001	SysML v2 API server is an optional dependency	Basic parsing works offline; validation requires API
OC-002	Container testing limited to CI environment	macOS development cannot test containers locally
OC-003	Git provider PAT required for private repositories	Public repos accessible without authentication

9.5.3 Assumptions

ID	Assumption	Risk if Invalid
A-001	MCP protocol spec stable through project duration	May require protocol updates
A-002	SysML v2 API spec stable (July 2025 OMG adoption)	May require API client changes
A-003	Rust MCP SDK (rmcp) supports required features	May need SDK contributions or workarounds
A-004	Git provider APIs stable for file operations	Low risk - mature APIs

9.6 Verification Methods

Per [1, Sec. 2.3.5.9], each requirement has an assigned verification method:

Method	Code	Description
Inspection	I	Visual examination of documentation, code
Analysis	A	Mathematical or logical evaluation
Demonstration	D	Functional operation without quantitative measurement
Test	T	Execution with quantitative measurement and pass/fail criteria

9.6.1 Verification Summary

Category	Test	Demonstration	Inspection	Total
FR-MCP	6	0	0	6
FR-REPO	7	0	0	7
FR-SYS	7	0	2	9
NFR-PERF	2	0	0	2
NFR-SEC	2	0	1	3
NFR-DEP	2	2	0	4
NFR-DOC	0	0	3	3
Total	26	2	6	34

9.7 Requirements Analysis

Per [1, Sec. 2.3.5.3], requirements must be analyzed for completeness, consistency, and feasibility.

9.7.1 Completeness Check

Criterion	Status	Notes
All stakeholder requirements traced	✓	See traceability matrix
All functional areas covered	✓	MCP, GitLab, SysML operations
NFRs address FURPS+	✓	Performance, Security, Deployment, Documentation
Verification method assigned	✓	All requirements have verification
Priority assigned	✓	High/Medium/Low for all

9.7.2 Consistency Check

Criterion	Status	Notes
No contradictory requirements	✓	Reviewed for conflicts
Terminology consistent	✓	Glossary in Appendix A
Units/formats consistent	✓	SI units, ISO date formats

9.7.3 Feasibility Assessment

Requirement Area	Feasibility	Risk
MCP Protocol	High	Official rmcp SDK provides implementation
Repository Integration	High	Provider-agnostic trait with GitLab implementation
SysML v2 Parsing (Subset)	High	Documented grammar subset achievable; see Section 12.2
SysML v2 Parsing (Full)	Low	Full compliance requires Xtext port or JVM interop; future work
SysML v2 API	Medium	Depends on API server availability
Container Deployment	High	Standard Rust cross-compilation

9.7.4 TBD Items

Item	Original Target	Disposition
OAuth authentication scope	PDR (Week 4)	Deferred — Phase 1 uses PAT authentication only (FR-REPO-005)
SysML v2 API error handling patterns	Week 7	Deferred — SysML v2 API integration deferred to post-capstone (R1 mitigation)
HTTP transport security (TLS) requirements	PDR (Week 4)	Deferred — HTTP transport is Phase 2+ scope; Phase 1 uses stdio only

9.8 Tool Definitions

9.8.1 Implemented (Phase 1 Complete)

Tool	Description	Status
`sysml_parse`	Parse SysML v2 text and extract elements with L0/L1/L2 detail levels	Complete
`sysml_validate`	Validate SysML v2 syntax via tree-sitter parse diagnostics	Complete
`sysml_list_definitions`	List definition names and types in SysML v2 text	Complete
`repo_list_files`	List files in Git repository (with optional `.sysml` filter)	Complete
`repo_get_file`	Read file content from Git repository	Complete

9.8.2 Planned (Phase 2+)

Tool	Description	Status
`sysml_validate` (API)	Full semantic validation via SysML v2 API server	Planned (extends current syntax validation)
`sysml_query`	Query model elements by type/properties	Planned
`repo_commit`	Commit changes to repository	Planned
`repo_create_mr`	Create merge/pull request	Planned

9.9 Resource Definitions

Resource URI	Phase	Description
`sysml://examples/{name}`	0	Bundled example models
`repo://{project}/file/{path}`	1	Git repository file access
`sysml://projects`	2	SysML v2 API project list