8  System Requirements Specification

8.1 Overview

This chapter defines the system requirements for the SysML v2 MCP Server per [1, Sec. 2.3.5.3]. Requirements are organized by functional area and traced to stakeholder requirements.

8.2 System Scope and Boundary

8.2.1 System Definition

The SysML v2 MCP Server is a software system that implements the Model Context Protocol (MCP) to provide AI assistants with programmatic access to SysML v2 models stored in GitLab repositories and managed by SysML v2 API servers.

8.2.2 System Boundary

                        ┌───────────────────────────────────┐
                        │         System Boundary           │
                        │                                   │
┌─────────────┐         │  ┌─────────────────────────────┐  │        ┌─────────────┐
│ MCP Client  │◄───────►│  │    SysML v2 MCP Server      │  │◄──────►│ GitLab API  │
│ (External)  │   MCP   │  │                             │  │  HTTP  │ (External)  │
└─────────────┘         │  │  ┌───────┐    ┌───────────┐ │  │        └─────────────┘
                        │  │  │ Tools │    │ Resources │ │  │
                        │  │  └───────┘    └───────────┘ │  │        ┌─────────────┐
                        │  │  ┌───────┐    ┌───────────┐ │  │◄──────►│ SysML v2    │
                        │  │  │Parser │    │  Config   │ │  │  HTTP  │ API Server  │
                        │  │  └───────┘    └───────────┘ │  │        │ (External)  │
                        │  └─────────────────────────────┘  │        └─────────────┘
                        │                                   │
                        └───────────────────────────────────┘

8.2.3 External Interfaces

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

Interface requirements need formal IR-xxx identifiers and detailed specifications. This will be addressed in the requirements pass.

8.3 Functional Requirements

8.3.1 MCP Protocol

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

8.3.2 GitLab Integration

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

8.3.3 SysML v2 Operations

ID Requirement Priority Verification Trace
FR-SYS-001 The server SHALL parse SysML v2 textual notation High Test SR-012
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

8.4 Non-Functional Requirements

8.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 -

8.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 -

8.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

8.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

8.5 Constraints and Assumptions

8.5.1 Design Constraints

ID Constraint Rationale
DC-001 The server SHALL be implemented in Go Aligns with GitLab ecosystem, single binary deployment
DC-002 The server SHALL use the official MCP Go SDK Ensures protocol compliance, Google co-maintained
DC-003 The server SHALL use go-gitlab client library Mature library, supports gitlab.com and self-hosted
DC-004 Container builds SHALL use Buildah/Podman OCI-compliant, rootless, CI-friendly

8.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 GitLab PAT required for private repositories Public repos accessible without authentication

8.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 Go MCP SDK supports required features May need SDK contributions or workarounds
A-004 GitLab API stable for file operations Low risk - mature API

8.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

8.6.1 Verification Summary

Category Test Demonstration Inspection Analysis Total
FR-MCP 6 0 0 0 6
FR-GL 6 0 1 0 7
FR-SYS 4 0 1 0 5
NFR-PERF 2 0 0 0 2
NFR-SEC 2 0 1 0 3
NFR-DEP 2 2 0 0 4
NFR-DOC 0 0 3 0 3
Total 22 2 6 0 30

8.7 Requirements Analysis

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

8.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

8.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

8.7.3 Feasibility Assessment

Requirement Area Feasibility Risk
MCP Protocol High SDK provides implementation
GitLab Integration High Mature go-gitlab library
SysML v2 Parsing Medium Basic parser feasible; full parser out of scope
SysML v2 API Medium Depends on API server availability
Container Deployment High Standard Go cross-compilation

8.7.4 TBD Items

Item Target Resolution Owner
OAuth authentication scope PDR (Week 4) Andrew
SysML v2 API error handling patterns Week 7 Andrew
HTTP transport security (TLS) requirements PDR (Week 4) Andrew

8.8 Tool Definitions

8.8.1 Phase 0 (Complete)

Tool Description Status
sysml_parse Parse SysML v2 textual notation and extract element information Complete

8.8.2 Phase 1 (GitLab)

Tool Description Status
gitlab_read_file Read .sysml file from GitLab repository Planned
gitlab_list_models List .sysml files in a repo/directory Planned

8.8.3 Phase 2 (SysML API)

Tool Description Status
sysml_validate Full validation via SysML v2 API server Planned
sysml_query Query model elements by type/properties Planned
gitlab_commit Commit changes to GitLab Planned
gitlab_create_mr Create merge request Planned

8.9 Resource Definitions

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