@nekzus/mcp-server 1.6.1 → 1.7.1

package/llms-full.txt

@@ -0,0 +1,582 @@
+# NPM Sentinel MCP Server - Full Documentation
+
+## Protocol Specification
+Version: 2025-05-11
+Transport: stdio
+Features: resources, tools, error handling
+
+## Architecture
+```mermaid
+flowchart TD
+    Client[MCP Client] <-->|MCP Protocol| Server[NPM Sentinel Server]
+    Server -->|Fetch| NPM[NPM Registry]
+    Server -->|Analysis| Security[Security DB]
+    Server -->|Metrics| Stats[Download Stats]
+    
+    subgraph Resources
+        NPM
+        Security
+        Stats
+    end
+    
+    subgraph Tools
+        Analysis[Package Analysis]
+        TypeScript[TS Support]
+        Performance[Performance]
+        Trends[Trend Analysis]
+    end
+```
+
+## Resources
+
+### npm://registry
+Content-Type: application/json
+Methods: GET, SUBSCRIBE
+Update Frequency: Real-time
+Rate Limits: Follows npm registry limits
+Description: Package metadata and version information interface
+
+### npm://security
+Content-Type: application/json
+Methods: GET
+Update Frequency: Daily
+Severity Levels: Low, Medium, High, Critical
+Description: Vulnerability and security analysis interface
+
+### npm://metrics
+Content-Type: application/json
+Methods: GET, SUBSCRIBE
+Update Frequency: Real-time
+Metrics Types: Downloads, Stars, Issues, Updates
+Description: Package analytics and statistics interface
+
+## Tool Specifications
+
+// Note: For all tools below, the response payload, typically as described by its `XYZResponse` interface 
+// (or a textual summary if the response is simpler), is JSON stringified and placed within the `text` field 
+// of the standard MCP content object: {"type": "text", "text": "...", "isError": boolean}.
+
+#### npmVersions
+```typescript
+interface NpmVersionsInput {
+  packages: string[];
+}
+
+interface VersionInfo {
+  version: string;
+  releaseDate: string;
+  deprecated?: boolean;
+  description?: string;
+}
+
+interface NpmVersionsResponse {
+  [packageName: string]: VersionInfo[];
+}
+```
+
+#### npmLatest
+```typescript
+interface NpmLatestInput {
+  packages: string[];
+}
+
+interface LatestInfo {
+  version: string;
+  releaseDate: string;
+  changelog?: string;
+}
+
+interface NpmLatestResponse {
+  [packageName: string]: LatestInfo;
+}
+```
+
+#### npmDeps
+```typescript
+interface NpmDepsInput {
+  packages: string[];
+}
+
+interface DependencyNode {
+  name: string;
+  version: string;
+  dependencies?: { [dependencyName: string]: string };
+}
+
+interface NpmDepsResponse {
+  [packageName: string]: {
+    dependencyTree?: DependencyNode;
+    analysisSummary?: string;
+  };
+}
+```
+
+#### npmTypes
+```typescript
+interface NpmTypesInput {
+  packages: string[];
+}
+
+interface TypeSupport {
+  hasTypes: boolean;
+  bundled: boolean;
+  definitelyTyped: boolean;
+  typeVersion?: string;
+}
+
+interface NpmTypesResponse {
+  [packageName: string]: TypeSupport;
+}
+```
+
+#### npmSize
+```typescript
+interface NpmSizeInput {
+  packages: string[];
+}
+
+interface SizeMetrics {
+  size: number; 
+  gzip: number; 
+  dependenciesCount: number;
+  treeshakeable?: boolean; 
+  assetSizes?: { assetName: string; size: number }[];
+}
+
+interface NpmSizeResponse {
+  [packageName: string]: SizeMetrics;
+}
+```
+
+#### npmVulnerabilities
+```typescript
+interface NpmVulnerabilitiesInput {
+  packages: string[];
+}
+
+interface Vulnerability {
+  severity: 'low' | 'medium' | 'high' | 'critical' | 'unknown';
+  title: string;
+  description: string;
+  affectedVersions: string;
+  recommendation?: string;
+  cvssScore?: number;
+  url?: string;
+}
+
+interface NpmVulnerabilitiesResponse {
+  [packageName: string]: Vulnerability[];
+}
+```
+
+#### npmTrends
+```typescript
+interface NpmTrendsInput {
+  packages: string[];
+  period: 'last-day' | 'last-week' | 'last-month' | 'last-year';
+}
+
+interface TrendDataPoint {
+  date: string;
+  downloads: number;
+}
+
+interface TrendMetrics {
+  period: string;
+  downloads: TrendDataPoint[];
+  growth?: number;
+  popularityScore?: number;
+}
+
+interface NpmTrendsResponse {
+  [packageName: string]: TrendMetrics;
+}
+```
+
+#### npmCompare
+```typescript
+interface NpmCompareInput {
+  packages: string[];
+}
+
+interface ComparisonAspects {
+  latestVersion?: string;
+  size?: SizeMetrics;
+  vulnerabilitiesCount?: number;
+  averageDownloads?: number;
+  qualityScore?: number;
+}
+
+interface NpmCompareResponse {
+  [packageName: string]: ComparisonAspects;
+  comparisonSummary?: string;
+}
+```
+
+#### npmMaintainers
+```typescript
+interface NpmMaintainersInput {
+  packages: string[];
+}
+
+interface Maintainer {
+  name: string;
+  email?: string;
+  githubUsername?: string;
+}
+
+interface NpmMaintainersResponse {
+  [packageName: string]: Maintainer[];
+}
+```
+
+#### npmScore
+```typescript
+interface NpmScoreInput {
+  packages: string[];
+}
+
+interface ScoreDetails {
+  quality: number;
+  popularity: number;
+  maintenance: number;
+  overall: number;
+}
+
+interface NpmScoreResponse {
+  [packageName: string]: ScoreDetails;
+}
+```
+
+#### npmPackageReadme
+```typescript
+interface NpmPackageReadmeInput {
+  packages: string[];
+}
+
+interface NpmPackageReadmeResponse {
+  [packageName: string]: {
+    content: string;
+    format: 'markdown' | 'text';
+    error?: string;
+  };
+}
+```
+
+#### npmSearch
+```typescript
+interface NpmSearchInput {
+  query: string;
+  limit?: number;
+}
+
+interface SearchResultPackage {
+  name: string;
+  version: string;
+  description?: string;
+  keywords?: string[];
+  score?: ScoreDetails;
+}
+
+interface NpmSearchResponse {
+  query: string;
+  results: SearchResultPackage[];
+  totalResults?: number;
+}
+```
+
+#### npmLicenseCompatibility
+```typescript
+interface NpmLicenseCompatibilityInput {
+  packages: string[];
+  projectLicense?: string;
+}
+
+interface LicenseInfo {
+  spdxId: string;
+  name: string;
+  isCompatible?: boolean;
+  issues?: string[];
+}
+
+interface NpmLicenseCompatibilityResponse {
+  [packageName: string]: LicenseInfo;
+  compatibilitySummary?: string;
+}
+```
+
+#### npmRepoStats
+```typescript
+interface NpmRepoStatsInput {
+  packages: string[];
+}
+
+interface RepoStats {
+  stars?: number;
+  forks?: number;
+  openIssues?: number;
+  lastCommitDate?: string;
+  contributorsCount?: number;
+  repoUrl?: string;
+}
+
+interface NpmRepoStatsResponse {
+  [packageName: string]: RepoStats;
+}
+```
+
+#### npmDeprecated
+```typescript
+interface NpmDeprecatedInput {
+  packages: string[];
+}
+
+interface DeprecationInfo {
+  isDeprecated: boolean;
+  message?: string;
+  alternative?: string;
+}
+
+interface NpmDeprecatedResponse {
+  [packageName: string]: DeprecationInfo;
+}
+```
+
+#### npmChangelogAnalysis
+```typescript
+interface NpmChangelogAnalysisInput {
+  packages: string[];
+  targetVersion?: string;
+  sinceVersion?: string;
+}
+
+interface ChangelogEntry {
+  version: string;
+  date?: string;
+  summary?: string;
+  changes?: { type: 'added' | 'fixed' | 'changed' | 'removed'; description: string }[];
+}
+
+interface NpmChangelogAnalysisResponse {
+  [packageName: string]: {
+    changelogUrl?: string;
+    entries?: ChangelogEntry[];
+    analysisSummary?: string;
+  };
+}
+```
+
+#### npmAlternatives
+```typescript
+interface NpmAlternativesInput {
+  packages: string[];
+}
+
+interface AlternativePackageInfo {
+  name: string;
+  reason?: string;
+  score?: ScoreDetails;
+}
+
+interface NpmAlternativesResponse {
+  [packageName: string]: {
+    alternatives: AlternativePackageInfo[];
+  };
+}
+```
+
+#### npmQuality
+```typescript
+interface NpmQualityInput {
+  packages: string[];
+}
+
+interface QualityMetrics {
+  codeComplexity?: number;
+  testCoverage?: number;
+  documentationScore?: number;
+  communityEngagement?: number;
+  npmsQualityScore?: number;
+  npmsPopularityScore?: number;
+  npmsMaintenanceScore?: number;
+}
+
+interface NpmQualityResponse {
+  [packageName: string]: QualityMetrics;
+}
+```
+
+#### npmMaintenance
+```typescript
+interface NpmMaintenanceInput {
+  packages: string[];
+}
+
+interface MaintenanceMetrics {
+  lastPublishDate?: string;
+  commitFrequency?: string;
+  openIssuesRatio?: number;
+  timeSinceLastCommit?: string;
+  npmsMaintenanceScore?: number;
+}
+
+interface NpmMaintenanceResponse {
+  [packageName: string]: MaintenanceMetrics;
+}
+```
+
+## Error Handling
+
+### Standard Error Format
+// When an error occurs, the standard MCP response 'content' object will have 'isError: true'.
+// The 'text' field of that content object will contain a JSON stringified MCPError object, as defined below.
+```typescript
+interface MCPError {
+  error: {
+    code: number;
+    message: string;
+    data?: {
+      details: string;
+      packageName?: string;
+      context?: any;
+    };
+  };
+}
+```
+
+### Error Codes
+1000: Invalid package name
+1001: Package not found
+1002: Version not found
+1003: Rate limit exceeded
+1004: Network error
+1005: Analysis failed
+2000: Internal server error
+
+## Security Considerations
+
+### Data Protection
+- All data is processed locally
+- No sensitive information is stored
+- Secure communication channels
+
+### Rate Limiting
+- Implements fair usage policies
+- Respects NPM registry limits
+- Prevents abuse
+
+### Authentication
+- Supports npm token authentication
+- Validates package access
+- Manages credentials securely
+
+## Integration Guide
+
+### Docker Configuration
+The server can be run in a Docker container with directory mounting to `/projects`. This allows for secure access to files while maintaining isolation.
+
+#### Build
+```bash
+# Build the Docker image
+docker build -t nekzus/npm-sentinel-mcp .
+```
+
+#### Basic Usage
+```json
+{
+  "mcpServers": {
+    "npm-sentinel-mcp": {
+      "command": "docker",
+      "args": [
+        "run",
+        "-i",
+        "--rm",
+        "-w", "/projects",
+        "--mount", "type=bind,src=${PWD},dst=/projects",
+        "nekzus/npm-sentinel-mcp",
+        "node",
+        "dist/index.js"
+      ]
+    }
+  }
+}
+```
+
+#### Multi-Directory Configuration
+```json
+{
+  "mcpServers": {
+    "npm-sentinel-mcp": {
+      "command": "docker",
+      "args": [
+        "run",
+        "-i",
+        "--rm",
+        "-w", "/projects",
+        "--mount", "type=bind,src=/path/to/workspace,dst=/projects/workspace",
+        "--mount", "type=bind,src=/path/to/other/dir,dst=/projects/other/dir,ro",
+        "nekzus/npm-sentinel-mcp",
+        "node",
+        "dist/index.js"
+      ]
+    }
+  }
+}
+```
+
+#### Mount Guidelines
+- Mount all directories under `/projects`
+- Use absolute paths for source directories
+- Add `,ro` flag for read-only access
+- Working directory is set to `/projects`
+- Container runs in interactive mode with auto-removal
+
+### Standard Configuration
+```json
+{
+  "mcpServers": {
+    "npm-sentinel-mcp": {
+      "transport": "stdio",
+      "command": "npx",
+      "args": ["-y", "@nekzus/mcp-server"]
+    }
+  }
+}
+```
+
+### Basic Usage
+```typescript
+// Initialize client
+const client = await MCPClient.connect("npm-sentinel-mcp");
+
+// Analyze package
+const result = await client.invoke("npmVersions", {
+  packages: ["react"]
+});
+
+// Subscribe to updates
+const unsubscribe = await client.subscribe("npm://registry", {
+  package: "react",
+  onUpdate: (data) => console.log(data)
+});
+```
+
+## Best Practices
+
+### Resource Usage
+1. Subscribe to resources for real-time updates
+2. Implement caching for frequently accessed data
+3. Use batch operations when possible
+4. Handle rate limits gracefully
+
+### Error Handling
+1. Implement proper error recovery
+2. Provide meaningful error messages
+3. Log errors for debugging
+4. Handle timeout scenarios
+
+### Performance
+1. Use connection pooling
+2. Implement request queuing
+3. Cache responses
+4. Handle concurrent requests 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nekzus/mcp-server",
-  "version": "1.6.1",
+  "version": "1.7.1",
   "description": "NPM Sentinel MCP - A powerful Model Context Protocol (MCP) server that revolutionizes NPM package analysis through AI. Built to integrate with Claude and Anthropic AI, it provides real-time intelligence on package security, dependencies, and performance.",
   "type": "module",
   "types": "./dist/index.d.ts",
@@ -11,6 +11,7 @@
   "files": [
     "dist",
     "README.md",
+    "llms-full.txt",
     "LICENSE"
   ],
   "scripts": {
@@ -75,7 +76,7 @@
   },
   "homepage": "https://github.com/Nekzus/npm-sentinel-mcp#readme",
   "dependencies": {
-    "@modelcontextprotocol/sdk": "1.11.1",
+    "@modelcontextprotocol/sdk": "1.11.2",
     "node-fetch": "3.3.2",
     "zod": "3.24.4"
   },