城市应急位置服务演示

CAMARA Location Services - Urban Emergency Demo

[!WARNING] Proof-of-concept / demo — not for production emergency-response deployment.

Info

This is a mvp proof-of-concept, minimal app demo, for using CAMARA Telecom Network SDKs/APIs, for integration to Emergency Systems (part of my other bigger project of Distributed Early Warning Emergency Systems), and part of the Global/Romania Developer Challenge, by ORANGE: Network APIs Hackathon 2025.

Background

• Here is a technical presentation article and here another general article with Business Cases;

• Here is an overview of product rationale and more information;

• Here is the live running demo (with backend generating fake data a endpoints, not real telecom API connected, which, for safety reasons is enabled only when is required from orange hackathon or others: https://camara-emergency.up.railway.app/;

• This app is based on CAMARA Unified OpenAPI and CAMARA SDK, unofficial helpers, to the official CAMARA Project;

• API Reference: https://github.com/andreibesleaga/camara-api-reference

Stack

Minimal full-stack demo: Node.js backend + React/Leaflet frontend + MCP bridge + mock generator, using camara-sdk and camara-mcp libraries, some with the help of AI.

Quick start

Requires Node.js >= 20.17 (the dependency tree includes ESM-only packages that need require(esm) support; node:20-alpine and Node 22/24 all work).

1. Copy .env.example to .env and set USE_MOCK=true
2. npm install
3. npm run build:full
4. npm run start -> open http://localhost:8080

Configuration

The .env.example file now documents all the inputs required to switch from mock data to live CAMARA Network APIs:

• Global CAMARA settings (CAMARA_BASE_URL, CAMARA_SANDBOX_CONTRACT_ID, CAMARA_OPERATOR_NAME, CAMARA_SCOPE, CAMARA_SCOPES).
• OAuth/OpenID Connect endpoints and credentials (CAMARA_OAUTH_*) to support client-credential exchanges against an operator sandbox.
• Per product overrides (CAMARA_POPULATION_DENSITY_*, CAMARA_REGION_DEVICE_COUNT_*, CAMARA_DEVICE_LOCATION_*, CAMARA_ALERTS_*) including usage mode flags (synchronous, asynchronous, subscription) and callback endpoints when a webhook is required.
• Callback defaults (CAMARA_CALLBACK_BASE_URL, CAMARA_CALLBACK_AUTH_HEADER) for operators that push events to the application.
• Orange developer placeholders (ORANGE_APPLICATION_ID, ORANGE_CLIENT_ID, ORANGE_CLIENT_SECRET, ORANGE_TOKEN_URL, ORANGE_SCOPES) matching the Network APIs Playground documentation.

Population density uses ngeohash cells returned by CAMARA to build the heatmap. Device location remains subscription-driven in live mode; the backend surfaces instructive errors until a webhook sink is configured. Leave USE_MOCK=true until valid sandbox credentials are supplied; once all required variables are filled, set USE_MOCK=false to start wiring the live CAMARA flows. (When checking against real APIs, check all the .env sandbox vars for correct endpoints, credentials, and other valid configs).

Backend Endpoints:

• GET /healthz (liveness probe)
• GET /readyz (readiness probe, reports mock/live mode)
• GET /api/health (status + mock flag)
• GET /api/location/device/:deviceId
• POST /api/density/snapshot
• GET /api/density/flow/:areaId
• POST /api/alerts/rules
• GET /api/alerts/rules
• DELETE /api/alerts/rules/:id
• GET /api/alerts/stream (SSE)
• POST /api/routing/plan
• POST /api/mcp/invoke

AI assistant & MCP usage

The camara-sdk repository ships with the generated CAMARA MCP server so you can give AI agents direct access to the same telecom APIs used by the demo front end.

1. Install the server (no build step required):

   复制

   npx -y camara-mcp@latest --client=claude --tools=dynamic
   

2. Export the CAMARA bearer keys or token exchange variables that correspond to the products you want the assistant to access. At minimum populate the notification keys generated by your operator sandbox, for example:

   复制

   export CAMARA_POPULATION_DENSITY_DATA_NOTIFICATIONS_API_KEY="..."
   export CAMARA_REGION_DEVICE_COUNT_NOTIFICATIONS_API_KEY="..."
   # add additional CAMARA_*_NOTIFICATIONS_API_KEY values as needed
   

   If your operator issues OAuth credentials instead of static keys, reuse the same environment variables documented earlier (CAMARA_OAUTH_*, CAMARA_*_SCOPES, etc.) before starting the server.

3. Point your MCP-compatible client (Cursor, Claude desktop, VS Code agents, etc.) at the server. A basic modelContextProtocol.json entry looks like:

   复制

   {
       "mcpServers": {
      	 "camara_sdk_api": {
      		 "command": "npx",
      		 "args": ["-y", "camara-mcp", "--client=cursor", "--tools=dynamic"],
      		 "env": {
      			 "CAMARA_POPULATION_DENSITY_DATA_NOTIFICATIONS_API_KEY": "..."
      		 }
      	 }
       }
   }
   

4. Inside the assistant, use the list_api_endpoints, get_api_endpoint_schema, and invoke_api_endpoint tools (exposed automatically when --tools=dynamic is set) to discover and execute CAMARA endpoints. You can narrow scope with command-line filters such as --resource=populationdensitydata or load prepared subsets with --tool / --no-tool flags.

Need to run the MCP server remotely? Launch it with npx camara-mcp --transport=http --port 3030 and configure your client to target http://localhost:3030, optionally passing the same filters as URL query parameters.

This demo should follow CAMARA API Design Guidelines and implements:

• CAMARA-compliant error responses (status, code, message)
• OAuth2 client_credentials flow with OpenID Connect discovery
• x-correlator header support for request traceability
• Proper resource naming matching camara-sdk conventions
• Comprehensive security features (rate limiting, helmet headers, CORS, sanitization)

Security Features

This application includes production-ready security features that are fully configurable:

• Rate Limiting - Protects against API abuse (100 requests/15min default)
• Helmet Security Headers - Sets secure HTTP headers (CSP, HSTS, etc.)
• CORS - Configurable cross-origin resource sharing
• NoSQL Injection Protection - Sanitizes request data
• HPP Protection - Prevents HTTP parameter pollution
• Response Compression - Reduces bandwidth usage
• Body Size Limits - Prevents DoS attacks
• Trust Proxy - Accurate IP detection behind load balancers

Quick Start:

# Development (permissive)
SECURITY_RATE_LIMIT_ENABLED=false
SECURITY_CORS_ORIGINS=*

# Production (strict)
SECURITY_RATE_LIMIT_ENABLED=true
SECURITY_CORS_ORIGINS=https://yourdomain.com
SECURITY_TRUST_PROXY=true

Documentation:

• Configuration: .env.example (see Security Configuration section)

All security features are enabled by default with safe settings and can be customized via environment variables.

Tests

End-to-end tests (Vitest + supertest) cover every REST endpoint in mock mode, including the health probes, validation errors, and the x-correlator guard.

npm test          # requires Node 20+

The Express app is exported from backend/app.ts; backend/server.ts only starts the listener, so the app can be imported by tests without binding a port.

Manual review checklist

• config: copy .env.example → .env; USE_MOCK=true for the demo, security vars optional
• run: npm install → npm run build:full → npm run start → http://localhost:8080
• examples: see Backend Endpoints above; AI/MCP usage via npx -y camara-mcp@latest
• result: map UI with mock device locations, density heatmap, alerts SSE, routing
• path: backend backend/ (app.ts, routes/, services/), frontend frontend/