@mcpspec/core 1.0.0 → 1.0.2
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +123 -0
- package/package.json +3 -3
package/README.md
ADDED
|
@@ -0,0 +1,123 @@
|
|
|
1
|
+
# @mcpspec/core
|
|
2
|
+
|
|
3
|
+
Core engine for [MCPSpec](https://www.npmjs.com/package/mcpspec) — MCP client, test runner, security scanner, performance profiler, documentation generator, and quality scorer.
|
|
4
|
+
|
|
5
|
+
> **For CLI usage, install [`mcpspec`](https://www.npmjs.com/package/mcpspec) instead.** This package is for programmatic use — embedding MCPSpec capabilities in your own tools.
|
|
6
|
+
|
|
7
|
+
## Installation
|
|
8
|
+
|
|
9
|
+
```bash
|
|
10
|
+
npm install @mcpspec/core
|
|
11
|
+
```
|
|
12
|
+
|
|
13
|
+
## Usage
|
|
14
|
+
|
|
15
|
+
### Connect to an MCP server
|
|
16
|
+
|
|
17
|
+
```typescript
|
|
18
|
+
import { MCPClient } from '@mcpspec/core';
|
|
19
|
+
|
|
20
|
+
const client = new MCPClient({
|
|
21
|
+
transport: 'stdio',
|
|
22
|
+
command: 'npx',
|
|
23
|
+
args: ['@modelcontextprotocol/server-filesystem', '/tmp'],
|
|
24
|
+
});
|
|
25
|
+
|
|
26
|
+
await client.connect();
|
|
27
|
+
const tools = await client.listTools();
|
|
28
|
+
const result = await client.callTool('read_file', { path: '/tmp/test.txt' });
|
|
29
|
+
await client.disconnect();
|
|
30
|
+
```
|
|
31
|
+
|
|
32
|
+
### Run a test collection
|
|
33
|
+
|
|
34
|
+
```typescript
|
|
35
|
+
import { TestRunner, ConsoleReporter, loadYamlSafely } from '@mcpspec/core';
|
|
36
|
+
import { readFileSync } from 'node:fs';
|
|
37
|
+
|
|
38
|
+
const yaml = readFileSync('./collection.yaml', 'utf-8');
|
|
39
|
+
const collection = loadYamlSafely(yaml);
|
|
40
|
+
|
|
41
|
+
const runner = new TestRunner();
|
|
42
|
+
const results = await runner.run(collection, {
|
|
43
|
+
reporter: new ConsoleReporter(),
|
|
44
|
+
});
|
|
45
|
+
|
|
46
|
+
console.log(`${results.summary.passed}/${results.summary.total} passed`);
|
|
47
|
+
```
|
|
48
|
+
|
|
49
|
+
## Exports
|
|
50
|
+
|
|
51
|
+
### Client
|
|
52
|
+
|
|
53
|
+
- `MCPClient` — Core MCP client (stdio, SSE, streamable-http transports)
|
|
54
|
+
- `MCPClientInterface` — Abstract interface for swappability
|
|
55
|
+
- `ConnectionManager` — Connection state machine with reconnection
|
|
56
|
+
- `LoggingTransport` — Protocol message logging
|
|
57
|
+
|
|
58
|
+
### Process Management
|
|
59
|
+
|
|
60
|
+
- `ProcessManagerImpl` — Spawn, monitor, and cleanup MCP server processes
|
|
61
|
+
- `ProcessRegistry` — Track all managed processes
|
|
62
|
+
- `registerCleanupHandlers` — Graceful shutdown on SIGINT/SIGTERM
|
|
63
|
+
|
|
64
|
+
### Testing
|
|
65
|
+
|
|
66
|
+
- `TestRunner` — Orchestrates collection execution
|
|
67
|
+
- `TestExecutor` — Executes individual test cases
|
|
68
|
+
- `TestScheduler` — Parallel execution with dependency resolution
|
|
69
|
+
|
|
70
|
+
### Assertions
|
|
71
|
+
|
|
72
|
+
Evaluated via `TestExecutor` — schema, equals, contains, exists, matches, type, length, latency, mimeType, expression (safe expr-eval).
|
|
73
|
+
|
|
74
|
+
### Reporters
|
|
75
|
+
|
|
76
|
+
- `ConsoleReporter` — Terminal output with colors
|
|
77
|
+
- `JsonReporter` — JSON output
|
|
78
|
+
- `JunitReporter` — JUnit XML for CI
|
|
79
|
+
- `HtmlReporter` — Standalone HTML report
|
|
80
|
+
- `TapReporter` — TAP protocol
|
|
81
|
+
|
|
82
|
+
### Comparison
|
|
83
|
+
|
|
84
|
+
- `BaselineStore` — Save and load test run baselines
|
|
85
|
+
- `ResultDiffer` — Diff two test runs
|
|
86
|
+
|
|
87
|
+
### Security
|
|
88
|
+
|
|
89
|
+
- `SecurityScanner` — Orchestrates security audits
|
|
90
|
+
- `ScanConfig` — Safety controls and mode filtering
|
|
91
|
+
- Rules: `PathTraversalRule`, `InputValidationRule`, `ResourceExhaustionRule`, `AuthBypassRule`, `InjectionRule`, `InformationDisclosureRule`
|
|
92
|
+
- `getSafePayloads`, `getPlatformPayloads`, `getPayloadsForMode` — Payload management
|
|
93
|
+
|
|
94
|
+
### Performance
|
|
95
|
+
|
|
96
|
+
- `Profiler`, `computeStats` — Timing and statistics
|
|
97
|
+
- `BenchmarkRunner` — Iterative benchmarking with warmup
|
|
98
|
+
- `WaterfallGenerator` — Waterfall chart data
|
|
99
|
+
|
|
100
|
+
### Documentation
|
|
101
|
+
|
|
102
|
+
- `DocGenerator` — Orchestrates doc generation from server introspection
|
|
103
|
+
- `MarkdownGenerator` — Markdown output
|
|
104
|
+
- `HtmlDocGenerator` — HTML output
|
|
105
|
+
|
|
106
|
+
### Scoring
|
|
107
|
+
|
|
108
|
+
- `MCPScoreCalculator` — 0–100 quality score across 5 categories
|
|
109
|
+
- `BadgeGenerator` — shields.io-style SVG badges
|
|
110
|
+
|
|
111
|
+
### Utilities
|
|
112
|
+
|
|
113
|
+
- `loadYamlSafely` — FAILSAFE_SCHEMA YAML parsing
|
|
114
|
+
- `SecretMasker` — Redact secrets from output
|
|
115
|
+
- `resolveVariables` — Template variable resolution
|
|
116
|
+
- `queryJsonPath` — JSONPath queries
|
|
117
|
+
- `getPlatformInfo` — Cross-platform data/config directories
|
|
118
|
+
- `RateLimiter` — Throttle MCP calls
|
|
119
|
+
- `MCPSpecError`, `formatError` — Structured error handling
|
|
120
|
+
|
|
121
|
+
## License
|
|
122
|
+
|
|
123
|
+
MIT
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@mcpspec/core",
|
|
3
|
-
"version": "1.0.
|
|
3
|
+
"version": "1.0.2",
|
|
4
4
|
"type": "module",
|
|
5
5
|
"main": "./dist/index.js",
|
|
6
6
|
"types": "./dist/index.d.ts",
|
|
@@ -16,7 +16,7 @@
|
|
|
16
16
|
"license": "MIT",
|
|
17
17
|
"repository": {
|
|
18
18
|
"type": "git",
|
|
19
|
-
"url": "https://github.com/
|
|
19
|
+
"url": "https://github.com/light-handle/mcpspec.git",
|
|
20
20
|
"directory": "packages/core"
|
|
21
21
|
},
|
|
22
22
|
"engines": {
|
|
@@ -31,7 +31,7 @@
|
|
|
31
31
|
"expr-eval": "^2.0.2",
|
|
32
32
|
"handlebars": "^4.7.8",
|
|
33
33
|
"zod": "^3.22.0",
|
|
34
|
-
"@mcpspec/shared": "1.0.
|
|
34
|
+
"@mcpspec/shared": "1.0.2"
|
|
35
35
|
},
|
|
36
36
|
"devDependencies": {
|
|
37
37
|
"@types/js-yaml": "^4.0.9",
|