Skip to content
Back to search

mcp-server

Model Context Protocol (MCP) TypeScript Monorepo

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/bhimprakashsingh--mcp-server/badge.svg)](/listings/bhimprakashsingh--mcp-server)

HTML

<a href="/listings/bhimprakashsingh--mcp-server"><img src="/api/listings/bhimprakashsingh--mcp-server/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

1. Install & Build

npm install
npm run build

---

2. Testing Authentication & Authorization

Step 1: Start the MCP Server in HTTP mode

npm run start:server:http

Step 2: Run the Security & RBAC Test Suite

npm run start:client

*The client demo automatically executes three test suites:* 1. **Admin Test**: Connects with `admin-token-secret-123`, creates a note, reads `config://server`, and deletes a note. 2. **Guest Test**: Connects with `guest-token-secret-789`, confirms math calculations are allowed, but verifies that creating notes or reading `config://server` is blocked with `403 Forbidden`. 3. **Invalid Token Test**: Attempts to connect with an invalid token and confirms the connection is rejected with `401 Unauthorized`.

---

3. Running the MCP Host

Automated End-to-End Demo:

npm run demo:host

Interactive CLI (with Auth):

npm run start:host

*Inside the CLI, type `/whoami` to inspect your active token and role permissions, or test slash commands like `/tools`, `/resources`, `/prompts`, and `/read system://info`.*

---

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 193 lines
  1. # Model Context Protocol (MCP) TypeScript Monorepo
  2. A comprehensive, production-ready TypeScript project implementing all three fundamental architectural roles of the **Model Context Protocol (MCP)**:
  3. 1. **Server (`@mcp-project/server`)**: Exposes tools, resources, and prompt templates over **HTTP (Server-Sent Events)** or standard I/O (**stdio**), guarded by **Authentication & Authorization (RBAC)**.
  4. 2. **Client (`@mcp-project/client`)**: A reusable, type-safe client library that connects to MCP servers over HTTP SSE or Stdio with Bearer Token authentication.
  5. 3. **Host (`@mcp-project/host`)**: The root orchestrator and application runtime (analogous to Claude Desktop or Antigravity) that authenticates against MCP servers, aggregates their tools and resources into a unified registry, and runs an intelligent AI Agent loop with an interactive CLI.
  6. ---
  7. ## Authentication & Authorization (RBAC)
  8. The project includes an end-to-end security layer supporting **Token Authentication** and **Role-Based Access Control (RBAC)**:
  9. ### 1. Authentication (AuthN)
  10. - **HTTP SSE**: Authenticates via `Authorization: Bearer <token>` header, `x-api-key` header, or URL query param `?token=<token>`. Unauthenticated requests receive `401 Unauthorized`.
  11. - **Stdio**: Authenticates via environment variable `MCP_AUTH_TOKEN`.
  12. ### 2. Authorization & Roles (AuthZ)
  13. | Role | Token | Scopes & Permissions | Allowed Capabilities | Restricted Capabilities |
  14. |------|-------|----------------------|----------------------|-------------------------|
  15. | **`admin`** | `admin-token-secret-123` | `*` (Full access) | All tools (`calculate`, `weather_report`, `get_system_info:detailed`, `manage_notes:create`, `read`, `list`, `delete`), all resources (`system://info`, `notes://all`, `config://server`), all prompts | None |
  16. | **`user`** | `user-token-secret-456` | `tools:*`, `notes:create/read/list`, `resources:system` | Math, weather, basic system info, creating & reading notes | Deleting notes (`notes:delete`), reading server config (`config://server`) |
  17. | **`guest`** | `guest-token-secret-789` | `tools:calculate`, `tools:weather`, `notes:read/list` | Math, weather, reading public notes | Creating notes, deleting notes, viewing system diagnostics or server config |
  18. ---
  19. ## Dynamic Server Resolution (No Hardcoded Paths)
  20. Neither `client` nor `host` hardcodes server file paths or URLs. Connection parameters are resolved dynamically via:
  21. 1. **`.env` file** (`MCP_SERVER_URL` or `MCP_SERVER_PATH`, plus `MCP_AUTH_TOKEN`)
  22. 2. **`mcp-config.json`** (`defaultServerUrl` or `defaultServerPath`)
  23. ### Setting up `.env`
  24. ```env
  25. # ==============================================================================
  26. # Model Context Protocol (MCP) Configuration (.env)
  27. # ==============================================================================
  28. # OPTION 1: HTTP SSE Transport (Remote or Local HTTP server)
  29. MCP_SERVER_URL=http://localhost:3001/sse
  30. # OPTION 2: Local Stdio Transport
  31. # MCP_SERVER_PATH=./packages/server/dist/index.js
  32. # Server Port and Transport Mode
  33. PORT=3001
  34. MCP_TRANSPORT=http
  35. # Authentication Tokens
  36. MCP_AUTH_TOKEN=admin-token-secret-123
  37. MCP_ADMIN_TOKEN=admin-token-secret-123
  38. MCP_USER_TOKEN=user-token-secret-456
  39. MCP_GUEST_TOKEN=guest-token-secret-789
  40. ```
  41. ---
  42. ## Architecture Overview
  43. ```
  44. ┌────────────────────────────────────────┐
  45. │ MCP HOST │
  46. │ (AI App / Orchestrator) │
  47. │ - Multi-server manager & aggregator │
  48. │ - Injects Auth Bearer Token │
  49. │ - Agent reasoning & tool planner │
  50. │ - Interactive CLI REPL / Demo runner │
  51. └──────────────────┬─────────────────────┘
  52. │
  53. ▼
  54. ┌────────────────────────────────────────┐
  55. │ MCP CLIENT │
  56. │ - Bearer token / x-api-key headers │
  57. │ - Automatic SSE or Stdio transport │
  58. │ - listTools / callTool │
  59. │ - listResources / readResource │
  60. │ - listPrompts / getPrompt │
  61. └──────────────────┬─────────────────────┘
  62. │
  63. HTTP SSE (with Auth) or Stdio
  64. │
  65. ▼
  66. ┌────────────────────────────────────────┐
  67. │ MCP SERVER │
  68. │ - AuthN: Token verification (401) │
  69. │ - AuthZ: RBAC permission checks (403) │
  70. │ - Tools: calculate, get_system_info, │
  71. │ manage_notes, weather_report │
  72. │ - Resources: system://info, │
  73. │ notes://all, │
  74. │ config://server │
  75. │ - Prompts: system_diagnostics, │
  76. │ summarize_notes │
  77. └────────────────────────────────────────┘
  78. ```
  79. ---
  80. ## Project Structure
  81. ```
  82. .
  83. ├── .env # Active environment & token configuration
  84. ├── .env.example # Template for environment settings
  85. ├── mcp-config.json # Fallback server path & URL configuration
  86. ├── packages/
  87. │ ├── server/ # MCP Server
  88. │ │ ├── src/
  89. │ │ │ ├── index.ts # Server entrypoint (HTTP SSE + Stdio + Auth)
  90. │ │ │ ├── auth.ts # Token verification & RBAC authorization
  91. │ │ │ ├── tools.ts # Tools with permission enforcement
  92. │ │ │ ├── resources.ts # Resources with access control
  93. │ │ │ ├── prompts.ts # Prompts with authorization
  94. │ │ │ └── types.ts # Server data types
  95. │ │ ├── package.json
  96. │ │ └── tsconfig.json
  97. │ │
  98. │ ├── client/ # MCP Client Library & Test Suite
  99. │ │ ├── src/
  100. │ │ │ ├── index.ts # Client RBAC verification test suite
  101. │ │ │ ├── client.ts # McpClient with HTTP SSE & Stdio Auth
  102. │ │ │ ├── config.ts # Dynamic .env & config file resolver
  103. │ │ │ └── types.ts # Client config & payload types
  104. │ │ ├── package.json
  105. │ │ └── tsconfig.json
  106. │ │
  107. │ └── host/ # MCP Host Runtime & Agent Loop
  108. │ ├── src/
  109. │ │ ├── index.ts # Host entrypoint (Interactive CLI & demo)
  110. │ │ ├── host.ts # McpHost registry & token injection
  111. │ │ ├── agent.ts # HostAgent reasoning & tool dispatch loop
  112. │ │ └── types.ts # Host interfaces & telemetry types
  113. │ ├── package.json
  114. │ └── tsconfig.json
  115. │
  116. ├── package.json # Monorepo root (npm workspaces)
  117. ├── tsconfig.base.json # Shared TypeScript compiler options
  118. ├── tsconfig.json # Project references root
  119. └── README.md # Documentation
  120. ```
  121. ---
  122. ## Getting Started
  123. ### 1. Install & Build
  124. ```bash
  125. npm install
  126. npm run build
  127. ```
  128. ---
  129. ### 2. Testing Authentication & Authorization
  130. #### Step 1: Start the MCP Server in HTTP mode
  131. ```bash
  132. npm run start:server:http
  133. ```
  134. #### Step 2: Run the Security & RBAC Test Suite
  135. ```bash
  136. npm run start:client
  137. ```
  138. *The client demo automatically executes three test suites:*
  139. 1. **Admin Test**: Connects with `admin-token-secret-123`, creates a note, reads `config://server`, and deletes a note.
  140. 2. **Guest Test**: Connects with `guest-token-secret-789`, confirms math calculations are allowed, but verifies that creating notes or reading `config://server` is blocked with `403 Forbidden`.
  141. 3. **Invalid Token Test**: Attempts to connect with an invalid token and confirms the connection is rejected with `401 Unauthorized`.
  142. ---
  143. ### 3. Running the MCP Host
  144. #### Automated End-to-End Demo:
  145. ```bash
  146. npm run demo:host
  147. ```
  148. #### Interactive CLI (with Auth):
  149. ```bash
  150. npm run start:host
  151. ```
  152. *Inside the CLI, type `/whoami` to inspect your active token and role permissions, or test slash commands like `/tools`, `/resources`, `/prompts`, and `/read system://info`.*
  153. ---
  154. ## License
  155. ISC

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.